mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-10 13:22:14 +00:00
Marc-André Bombeck
375ca12b05
scripts/bench/seed-large-account.ts (moved from scripts/, extended) writes one synthetic account of ten years: 1,265,561 measurement rows across the main types and five sources (Apple Health dense spot rows, Withings blood pressure and scale, a weekly manual weight, three years of Oura nightly values, 90 days of Nightscout CGM), `stats:` and per-sample cumulative rows, nightly sleep stages, 3,020 workouts, 1,095 mood entries and three medications with 3,285 intake events. Everything goes in through set-based INSERT … SELECT generate_series; values and timestamps are functions of the row index and `--anchor`, so a run is reproducible. The rollup tier is folded with recomputeUserRollups, as the boot backfill does, and the tables are analysed. About 80 s on the Mac mini. scripts/bench/run.ts boots the production build once with every role (so the queues exist), then measures against a web-only process under the production heap ceiling: p50, p95 and max latency and SQL statements per request (pg_stat_statements, read once nothing is in flight and the count holds still) for /api/auth/me, the dashboard summary and snapshot, the pulse series over 30, 365 and 3650 days, the day view, insights health status and correlations, each cold (caches evicted by a one-row manual-sync ingest before every request) and warm, plus a 5,000-row batch ingest as ten requests of 500. It writes JSON and a markdown table. docs/contributing/benchmarks.md describes the setup against a throwaway Postgres in Docker with the production pg_stat_statements settings.
71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
# `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/`](./api/) — the OpenAPI 3.1 spec for the native-client subset
|
|
(iOS DTO codegen target). See [`api/README.md`](./api/README.md) for
|
|
the preview commands. Also home to the MCP-server contract:
|
|
[`api/mcp-capabilities.md`](./api/mcp-capabilities.md) (tools,
|
|
resources, prompts, write model) and
|
|
[`api/mcp-skills.md`](./api/mcp-skills.md) (building a connector / skill).
|
|
- [`ops/`](./ops/) — operator runbooks: deploy, backup / restore,
|
|
encryption-key rotation, password reset and account recovery, env
|
|
checks, TLS pinning, data repair. These are what an operator reaches
|
|
for during an incident.
|
|
- [`self-hosting/`](./self-hosting/) — horizontal-scaling notes
|
|
(`HEALTHLOG_PROCESS_TYPE=web|worker|all`) and the deploy-pipeline
|
|
recipe. Routine install steps stay on `docs.healthlog.dev`. Includes
|
|
[`self-hosting/mcp.md`](./self-hosting/mcp.md) — enabling the
|
|
off-by-default MCP connector and pointing Claude.ai / ChatGPT /
|
|
Claude Desktop at it, and [`self-hosting/sso.md`](./self-hosting/sso.md)
|
|
— OIDC SSO login: IdP setup, the identity-pinning security model,
|
|
`OIDC_ONLY` consequences, and the break-glass runbook. Also
|
|
[`self-hosting/geolite2.md`](./self-hosting/geolite2.md) — bringing your
|
|
own offline GeoLite2 databases via `GEOLITE2_DIR` instead of sending
|
|
login IPs to a third-party lookup. And
|
|
[`self-hosting/account-sharing.md`](./self-hosting/account-sharing.md) —
|
|
letting one account on the instance open another's health record: the
|
|
three access levels, the eight sections a grant can be narrowed to,
|
|
managed profiles for somebody with no login and the guardians who look
|
|
after them, what revocation does and does not undo, and which trust
|
|
properties of the instance are unchanged by any of it. And
|
|
[`self-hosting/support.md`](./self-hosting/support.md) — reporting a
|
|
problem: error ids, the support info every account can copy, the
|
|
operator's redacted support report, and finding an error in the admin log.
|
|
- [`using/`](./using/) — notes on using the app that sit close to the
|
|
code. [`using/search.md`](./using/search.md) covers the command palette's
|
|
record search: opening it, what it finds, how matching works, and its
|
|
limits on very large and shared records.
|
|
- [`migration/`](./migration/) — migration notes. Currently only
|
|
v1.3 to v1.4; later releases are covered by `CHANGELOG.md` and
|
|
<https://docs.healthlog.dev>.
|
|
- [`integrations/`](./integrations/) — per-integration reference
|
|
(Withings, Fitbit, Google Health, WHOOP, Apple Health, AI providers,
|
|
data import).
|
|
- [`adr/`](./adr/) — architecture decision records.
|
|
- [`security/`](./security/) — threat-model notes.
|
|
- [`diagrams/`](./diagrams/) — architecture diagrams rendered through
|
|
docs.healthlog.dev.
|
|
- [`releases/`](./releases/) — release imagery.
|
|
- [`apple-store-connect-checklist.md`](./apple-store-connect-checklist.md)
|
|
— the iOS submission gate.
|
|
- [`codex-protocol-spec.md`](./codex-protocol-spec.md) — Codex / ChatGPT
|
|
OAuth protocol reverse-engineering notes.
|
|
- [`contributing/ui-standards.md`](./contributing/ui-standards.md) — the
|
|
binding UI standards: card anatomy, spacing, text colour, tokens and
|
|
which primitive to use where. Read before touching any surface.
|
|
- [`contributing/benchmarks.md`](./contributing/benchmarks.md) — the
|
|
large-account benchmark (latency and statements per request) and the
|
|
statement budgets on the hot routes.
|
|
- [`ui-guidelines.md`](./ui-guidelines.md) — UI / a11y house style; where
|
|
it disagrees with the UI standards, the standards win.
|
|
|
|
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](../README.md#quick-start).
|