mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
0e301b580c
POST /api/insights/ecg takes one recording per request: the stable recording id the client already has, the on-device timestamp, the sampling rate, the waveform as integer micro-volts, the lead, the average heart rate, and the device's own verdict. Same gating as the reads (auth, the insights module, the insightStatus surface), userId from the session, APPLE_HEALTH the only source a client may claim. sampleCount and durationSeconds are derived here, and nothing about the waveform is ever interpreted. The write body now lives in one place, src/lib/ecg/persist-recording.ts, shared by the Withings sync, the export-archive importer and the new route. Three writers with three persistence bodies is how the two ends of one rule drift apart. Migration 0291 adds the second unique index on (user_id, source, recorded_at, sampling_frequency). The archive importer identifies a strip by a hash of its content and a live client by the device's own sample uuid, so the same physical recording arriving through both doors carried two different ids and would have landed twice. One device does not record two different strips at the same instant at the same sampling rate, so the constraint is sound and the convergence stops being a convention. The table already holds rows on deployed instances and two writers have been filling it since v1.19.0, so the index cannot just be created: a pre-existing collision would abort the migration. The migration resolves duplicates first, keeping the row with the most samples (a stored strip beats a verdict-only row), then the one linked to its event measurement, then the most recently written, then the lowest id so the choice is total. The losers' event link is salvaged onto the keeper first, so resolving a duplicate never costs the recording its place in the event timeline. If that resolution is wrong on some instance, the failure is visible at deploy time and not later: db:migrate:deploy runs on boot, so the container crash-loops with the migration named in the logs and the release never serves traffic. A deploy that finishes in under thirty seconds did not run it. The GET list and detail routes and the export-archive path are unchanged; this is a second door, not a replacement.
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).