# Private Health Records · 健康紀錄

A Traditional Chinese/English health-record dashboard with bodyweight and strength-training records, an interactive ChatGPT MCP interface, bounded multi-image/multi-session review, typed scale metrics, structured capture/measurement provenance, drafts, reversible deletion, and JSON export.

**Source snapshot:** the running deployment remains private and separate from this source. Original code and associated documentation are licensed under [MIT](LICENSE). See [LICENSE-STATUS.md](LICENSE-STATUS.md) for scope and third-party terms.

## Languages and image-upload scenarios

The existing Web App/PWA and embedded interactive frontend support Traditional
Chinese and English with Auto/manual switching. Standalone Auto follows browser
languages; embedded Auto uses actually supplied host locale hints before browser
fallback. Only manual locale preference is persisted, and switching never rewrites
original record text, values or identifiers. Shared dictionaries/resolution live
in `lib/locale-messages.ts` and `lib/i18n.ts`; adding another language means adding
a complete dictionary, defining any needed tag aliases and adding its native-name
selector option. The offline shell is regenerated by `scripts/build-locale-shell.mjs`.
Explicit Simplified Chinese hints fall
back to another supported language; Simplified translation is not claimed.

Read the bilingual [expected user scenarios](docs/image-upload-scenarios.md) for
the included synthetic scale test card, workout-screenshot scenarios,
review/consent/retry/correction, Auto/manual language behavior and the distinction between current D1 functionality
and planned standalone plan-backed analysis/common Library or Space storage. The
standalone app starts with batch upload. Its optional **interim BYOK demonstration**
uses a user-entered key in page memory and sends sanitized images directly to
OpenAI; API usage is billed to that user. Results appear for one review/save,
with corrections behind **Edit**. The intended product uses ChatGPT account and
intelligence integration without requiring a user API key; BYOK exercises the
flow until that integration is available. No operator credential or key relay is included.
Open **Settings** to enter a key before or after selecting photos. Keys are held
only for this visit; Close, Cancel or Escape discards an unapplied replacement.
The upload card keeps demo/privacy details in disclosures, while the provider,
separate API billing and explicit sending consent remain visible before analysis.
ChatGPT-native standalone inference and common Library/Space storage remain
unavailable. No real key or paid inference was used in validation. This document
supports the pending official access application; it does not claim approval or
alter a running deployment.

## Privacy and scope

- Real records require both an authenticated owner identity and explicit server-side consent. They are disabled by default.
- Synthetic demo data is isolated from real records. All included examples and test values are synthetic.
- The app stores structured records in Cloudflare D1, not original photos, GPS, credentials, or image URLs.
- The embedded photo flow extracts only bounded JPEG date metadata and re-encodes pixels before sending them through the active ChatGPT host's image channel. Missing or conflicting dates remain explicit; upload time is never substituted for measurement time.
- The host may receive the selected image after the user agrees. Standalone BYOK analysis is foreground-only and requires explicit key-risk, image-transmission and user-billing consent; no operator key or background service is provided.
- Deletion is reversible. Export is owner-scoped and bounded. The PWA caches only a generic offline shell, never health responses or authenticated pages.
- Experimental synthetic event discovery is present, but subscriptions fail closed. No background upload queue, webhook sender, or automatic background analysis is enabled.

This is a personal-record prototype, not a medical device, diagnosis service, or promise of regulatory compliance.

## Local development

Requirements: Node.js 22.13 or newer and npm. A fresh dependency install requires access to the public package registry. No account, cloud credential, or real health data is needed for local synthetic testing.

```sh
npm ci
cp .dev.vars.example .dev.vars
npm run db:migrate:local
npm run dev
```

Open the loopback address printed by the dev server, normally `http://127.0.0.1:5173`. The local sign-in flow creates a deliberately synthetic identity and is restricted to loopback. Real-record mode stays disabled. Do not expose this mock-login server to the internet.

`HEALTH_PUBLIC_ORIGIN` controls the embedded widget's full-report link. It accepts an HTTPS origin, or HTTP on loopback for local development. Blank or invalid input disables the link. Never point it to someone else's private deployment.

The `.openai/hosting.json` file contains only generic binding declarations. It deliberately contains no account or project identifier. The placeholder database ID in `wrangler.local.jsonc` is only for isolated local development.

## Checks

```sh
npm test
npm run test:integration
npm run test:races
npm run test:events
npm run typecheck
npm run lint
npm run build
npm run test:built-widget
npm run audit:source
```

Tests create only synthetic fixtures in isolated local Miniflare databases. Do not run tests against an existing personal-health database. See [SOURCE-REVIEW.md](SOURCE-REVIEW.md) for the candidate's verification results and remaining limitations.

## Architecture and deployment

Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md), and [SECURITY.md](SECURITY.md) before hosting real records.

The current runtime targets Cloudflare Workers/D1 through Vite and Vinext. Production identity is supplied by a trusted Sites authentication gateway. This source package does not include an independently deployable OAuth/SIWC server, credentials, or a general-purpose secure authentication gateway.

Opening the source does not make a deployment public, establish eligibility for any external program, grant ChatGPT model tokens, or enable inference outside a supported host. Verify any external program's current official requirements separately.

## Features and limits

- Batch input supports 8 photos/screenshots, 10 MB each / 30 MB originals total, 40 MB sanitized pixels and 64 million decoded pixels total; 16 sessions / 64 observations per reviewed batch
- One screenshot can supply multiple dated sessions; same-day sessions remain separate, with visible-date suggestions and explicit move/split/merge review
- Typed skeletal/total muscle mass and percentages, explicit custom metrics, source/observation provenance, duplicate consolidation and conflict/exclusion review
- Capture evidence stays separate from measurement date/time/precision/timezone; missing metadata stays unknown, no device-zone default, and DST ambiguity requires clarification
- All photo analysis creates pending drafts. One explicit guarded, idempotent D1 confirmation saves every reviewed session atomically, then canonical readback verifies the full batch
- Session reports/trends group matching metrics/units, preserve date-only precision, and exclude pending/deleted batches; batch deletion/restoration is explicit and reversible
- Widget resource `ui://health/records-v5.html` is advertised; v4 resource reads remain compatible. Refresh tool metadata for the new batch tools
- Migration `0003_measurement_batches.sql` adds two tables only; apply it before serving the new snapshot. Existing migrations, records and authorization are preserved


- Bodyweight/body-fat and strength-training entry types
- Draft correction and explicit confirmation, source-key idempotency, and owner-scoped audit events
- Separate real/demo namespaces, trash and restore, structured JSON export
- A default list page holds 500 records; the UI can load further pages and labels partial chart data
- Export is bounded to 10,000 records/drafts and errors explicitly above the bound; pending-draft UI currently shows the latest 100
- JPEG date metadata is supported; unsupported/corrupt/missing EXIF remains explicit, and HEIC must be converted and its date checked
- The real-photo mobile flow and model accuracy require separate device/host validation; automated tests do not prove either

## Licensing

Original code and associated documentation are licensed under the [MIT License](LICENSE), copyright (c) 2026 Allen Lee.

Third-party source and dependencies retain their own licenses and copyright notices. See [LICENSE-STATUS.md](LICENSE-STATUS.md), [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), and the [dependency inventory](docs/dependency-inventory.csv) for their scopes and redistribution considerations.