mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
cc98c56172
The setup questionnaire the design spec asks for needs somewhere to put its answers. `OnboardingRecord` is that place: one row per RECORD rather than per person, so a guardian running a managed profile's setup writes the child's row and not their own, and the three JSON columns hold the answers, the nine ordered steps with their status, and the one task the flow ends on. Nothing here is encrypted, and the schema comment says why: the columns hold closed enum vocabularies, not free text, which is the same class of value as the module map and the goal slugs sitting in plaintext beside them. The needs to modules map lives next to the module keys rather than in the flow, because a module renamed or retired has to break the map at compile time rather than leave a chip that quietly changes nothing. The derivation is total — every directly-owned key gets an explicit value — and the merge beside it is one-directional: what the answers name is switched on, what they do not name is switched off only where the record does not already carry a deliberate on. The two delegated keys are absent by construction: `cycle` is reported separately because its real column is on the cycle profile, and the Coach is not offered by this flow at all. Readers are fail-soft. They sit on the payload that rides every app boot, and a value written by a release that named an area this one retired must not take the shell down with it. Nothing is retired: the four-step wizard, its goal slugs and the one-time tile seed keep working and keep their meaning until the new surface replaces them. The two states are disjoint — the slugs decide tile order, these answers decide which modules are on, and neither reads the other.
prisma/
The database layer. HealthLog runs PostgreSQL 16 via Prisma 7. This directory holds the single schema file and the forward-only migration history; the generated client is emitted elsewhere.
Contents
schema.prisma— 61 models, one file.cuid()primary keys,snake_casecolumns via@map(...), encrypted columns mostly suffixed*Encrypted(search the file; there are 24 encrypted column references). Thegenerator clientblock emits to../src/generated/prisma(imported as@/generated/prisma).migrations/— numbered, forward-only SQL migrations (0001_…upward).migration_lock.tomlpins the provider topostgresql.
Migration workflow
# author a migration from a schema edit
pnpm dlx prisma migrate dev --name <short_snake_case_name>
# regenerate the client after any schema change
pnpm dlx prisma generate
Number a new migration with the next free prefix. The production entrypoint runs prisma migrate deploy on boot, so every migration must apply cleanly forward — there is no down-migration path. Always include the migration file in the same change as the schema edit.
Conventions
- Encryption is fail-closed:
*Encryptedcolumns are written through@/lib/crypto(AES-256-GCM, versioned key ids); never store plaintext in an encrypted column. Key rotation isscripts/rotate-encryption-key.ts+docs/ops/encryption-key-rotation.md. - The generated client under
src/generated/prismais build output — do not edit it. - Schema-touching changes that affect the API surface must regenerate
docs/api/openapi.yaml(see../CLAUDE.md).
Related: ../src/lib/README.md (db.ts, rollups/), ../docs/ops/ (migrations + backup runbooks).