mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
9eed407ccc
The dense hourly fold only took Apple Health and Health Connect samples, so heart rate from the provider syncs that store one row per sample stayed raw forever. One self-hosted account held about 25 million Google Health pulse rows after a full-history backfill, and every reader and fold that falls back to the raw table paid for it (#1297). The fold now walks a map of sources to the dense types each stores sample by sample: every dense type for Apple Health and Health Connect, heart rate for Google Health and Oura. Their daily SpO2 values are no intraday stream and stay as they are; Fitbit does not sync intraday heart rate, and WHOOP, Withings and Polar write dense types only once per recovery, night or spot check. Each source folds into its own hourly stats rows, and the DAY rollup is still taken from the raw samples before they go. The fold deletes the samples it averages, and the provider syncs write first-write-wins on the externalId, so a backfill or full sync would have put every folded sample back. Google Health would even have re-keyed an hourly row into a sample that fell on its anchor through the natural-key rescue. The folded_window rule now has one hour rule per fold source, and both syncs drop the samples of an hour the fold already took before they write. Recent samples cost no lookup. The boot discovery of the fold probes each account and source for the first raw sample it would take instead of grouping every such row, and the one-time fold repair stays on the two sources it was written for.
src/lib/
The server and runtime toolkit. Everything that is not a page, component, or route handler lives here: the API kit, auth, crypto, the rollup tier, AI providers, notifications, background jobs, and the integration clients. Route handlers and RSC pages compose these modules; the modules never reach back into app/.
Core request kit
api-handler.ts— theapiHandlerwrapper every route uses (Wide-Event builder, error envelope, GlitchTip forwarder) and the one public entry for the request guards inauth/guards/: the auth resolver (cookie OR Bearer),requireAuth/requireRecordAuth/requireAdmin(admin is cookie-only by construction), the step-up gates.api-response.ts— the{ data, error, meta? }envelope:apiSuccess/apiError,safeJson, trusted-proxy IP resolver,returnAllZodIssues+sanitiseZodIssues.rate-limit.ts— Postgres-backed sliding-window limiter (single atomic upsert); multi-instance correct.idempotency.ts— user-scoped idempotency keys that refuse to cache secret-shaped responses.query-keys/— the only legal source of TanStack QueryqueryKey/mutationKeyarrays (enforced by an ESLint rule); per-feature files behind theindex.tsbarrel.safe-fetch.ts— the one documented outbound-egress entry (redirect: "manual"+ timeout; optional connect-time DNS-rebinding pin). Rawfetch(underlib/+app/is banned by ESLint.db.ts— the Prisma client singleton.crypto.ts— AES-256-GCM at rest with versioned key ids, fail-closed loader, rotation primitives.
Subsystems
auth/— Postgres sessions, secure-cookie flag policy, passkey (WebAuthn) + Argon2id password, per-device refresh-token rotation, HMAC Bearer tokens.ai/— multi-provider insight + Coach engine:provider-chain.ts, hand-rolled{openai,anthropic,local,codex,mock}-client.ts,coach/,prompts/, citation + confidence helpers.rollups/— DAY/WEEK/MONTH/YEAR pre-aggregations for measurements, mood, and medication compliance. Read-swap pattern: probe the rollup, fall back to live SQL on a coverage miss.notifications/— the dispatcher cascade (APNs → Telegram → ntfy → Web Push), per-channelsenders/, retry policy, VAPID config.jobs/— pg-boss workers: reminders, insight pre-generation, backups, retention sweeps, integration backfills. Recurring work belongs here, not inscripts/.integrations/,withings/,whoop/,fitbit/— OAuth clients and sync services for the device providers;sync/holds the shared delta-feed plumbing.analytics/— trend calculations, cadence-aware medicationcompliance.ts, correlations.insights/,fhir/,doctor-report-*.ts— insight pipeline, FHIR R4 export, client-side doctor-report PDF.openapi/— Zod registry that is the source of truth fordocs/api/openapi.yaml.logging/,observability/,monitoring/— Wide-Event transports and the central redaction denylists (redact at the egress boundary, not the call site).validations/— shared Zod schemas, including the SSRFisPublicUrlfloor.i18n/,tz/+timezone.ts,format*.ts— translations, timezone helpers (Berlin for display, UTC in DB), locale formatting.
Conventions
Kebab-case filenames. See ../../CLAUDE.md "Code conventions" and "Security-relevant patterns"; the critical-files map there cites the exact entry points. Most modules carry tests in a sibling __tests__/.