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.
docs/ — internal reference + operator playbooks
The user-facing documentation lives at https://docs.healthlog.dev — that's the canonical surface for self-hosting guides, integration walkthroughs, AI-provider setup, and the doctor-report workflow.
The files in this directory are the internal operator playbooks, audit notes, and machine-readable specs that ship alongside the source:
api/— the OpenAPI 3.1 spec for the native-client subset (iOS DTO codegen target). Seeapi/README.mdfor the preview commands. Also home to the MCP-server contract:api/mcp-capabilities.md(tools, resources, prompts, write model) andapi/mcp-skills.md(building a connector / skill).ops/— backup / restore + encryption-key-rotation playbooks. These are the runbooks an operator reaches for during an incident.self-hosting/— horizontal-scaling notes (HEALTHLOG_PROCESS_TYPE=web|worker|all) and the deploy-pipeline recipe. Routine install steps stay ondocs.healthlog.dev. Includesself-hosting/mcp.md— enabling the off-by-default MCP connector and pointing Claude.ai / ChatGPT / Claude Desktop at it, andself-hosting/sso.md— OIDC SSO login: IdP setup, the identity-pinning security model,OIDC_ONLYconsequences, and the break-glass runbook. Alsoself-hosting/geolite2.md— bringing your own offline GeoLite2 databases viaGEOLITE2_DIRinstead of sending login IPs to a third-party lookup.migration/— release-by-release migration notes. Read the entry for the version you're upgrading from.audit/— per-release audit summaries archived for forensic traceability.apple-store-connect-checklist.md— the iOS submission gate.doctor-report.md— PDF generator design notes.codex-protocol-spec.md— Codex / ChatGPT OAuth protocol reverse-engineering notes.ui-guidelines.md— UI / a11y house style.
If you're a self-hoster looking to spin up an instance, start at https://docs.healthlog.dev or jump to the Quick Start in the project README.