mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 20:42:43 +00:00
Marc-André Bombeck
c33f7f9f6a
The snapshot gains the day's two readings with the age of the second one, through the same reader the page uses, so the page and the assistant cannot disagree about what today's comparison is. The freshness rule is the shared one: a comparison about the day before yesterday carries the date it is about and an instruction not to state it as today. Absence is a present field rather than a missing key — a model told "there is none yet" says so, and a model told nothing estimates one. The wording rule travels with the values, because a model handed a number and no instruction writes the sentence its training suggests, and about a forecast that sentence is a causal one. The contract publishes the resolved value: the expected figure, the band, the count, the deviation against the band, the age, and the contributions that carried weight. Nothing is left for a client to re-derive — two clients deriving the same figure about somebody's health record is how they start disagreeing about it. The description carries the observational wording and the display rule: the count goes wherever the value goes. The end-to-end proof runs against real Postgres and reads the table rather than a return value: nothing written a day short of the threshold, a banded and counted row on the day it crosses, the provisional label dropped at sixty days, the rows cleared when the module goes off, the rows cleared when entries are deleted back below the threshold, and an older pass's row replaced rather than left beside a fresh one. A delegate holding only the mind section is refused, and the assertion is on the response bytes.
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__/.