mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 04:32:42 +00:00
Marc-André Bombeck
bcb7716ffa
A restored account got a Coach that had never spoken to it. The conversations, every turn in them, and the record of which vault documents a thread was grounded in were all classified as backed up and travelled with nothing. The register's own entry for the messages called them the largest volume of free text an account owns after its documents. The three travel together because two of them mean nothing alone: a turn without its thread has nowhere to hang, and an attachment names a pairing rather than a thing. documentScoped is the field that makes this more than lost history. It is a permanent fence — set when a conversation is created through the fenced endpoint or gets its first document, and lowered by no code path anywhere, not by detaching every document and not by deleting one. A restore that let it default to false would hand the tool loop back to precisely the conversations the fence exists to keep away from it, and nothing in the interface would look wrong afterwards. So it is carried verbatim, restored verbatim, and asserted per thread rather than in aggregate: a restore that wrote false everywhere would still return both threads and every turn and satisfy every count. Prose follows the contract the rest of the payload already uses. A disaster-recovery file carries the stored ciphertext; a portable file carries the text, because a portable export exists to be readable by the person who owns it, exactly as it already decrypts medication notes, mood notes and document summaries. A single row under a key the instance no longer holds is named rather than thrown, so one unreadable turn cannot cost someone the rest of the transcript. Ids ride in both modes, as the reminders do, so an attachment resolves and the facts, plans and reminders still owed have something real to point at. The restore runs after the documents for the same reason, and an attachment naming a document the file does not carry is dropped and reported instead of failing the whole file over one link. Verified by breaking it: forcing documentScoped to false on the way back fails the round trip on that field by name.
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. Auth resolver (cookie OR Bearer),requireAuth/requireAdmin(admin is cookie-only by construction), idempotency plumbing, Wide-Event builder, GlitchTip forwarder.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__/.