Run it, read it, test it.

• clinicalbrief-backend

  FastAPI on Python 3.12 only. Ingestion adapters, the AI pipeline, search, FHIR export, the REST API with role and patient checks, and the SQL migrations (schema and row-level security, the source of truth for Postgres).

• clinicalbrief-frontend

  Next.js 16 with Supabase Auth. It reads clinical data only through the API, sending the session token as a Bearer header.

Local development can use SQLite (clinicalbrief_dev.db), created from the ORM. It has no migration path: after model changes, delete it and re-import. For the architecture story, see About ClinicalBrief.

Prerequisites

• Python 3.12 (commands use py -3.12)
• Node.js with npm
• A Supabase project, for sign-in and the Postgres database
• Optional: Ollama with qwen3.5, for the Copilot

1. Database

In the Supabase SQL editor, run every file in clinicalbrief-backend/migrations/ in order. There is no 0006.

2. Environment

Copy clinicalbrief-backend/.env.example to .env and clinicalbrief-frontend/.env.example to .env.local, then fill them in. Never put a service-role or secret key in the frontend.

3. Remote database opt-in

When DATABASE_URL points at Supabase, the backend and CLI refuse to start unless CLINICALBRIEF_ALLOW_REMOTE_DB=1 is set for that process. Keep it out of .env, so scripts and tests can never write to live data by default. CLI write commands print the target database first.

$env:CLINICALBRIEF_ALLOW_REMOTE_DB="1"   # PowerShell, current process only

4. Backend

cd clinicalbrief-backendpy -3.12 -m pip install -r requirements-dev.txtpy -3.12 -m app.cli import synthea ../data/raw/synthea-fhirpy -3.12 -m uvicorn app.main:app --reload --no-access-log

--no-access-log is deliberate: uvicorn's access log prints full URLs, which contain patient ids. The app records route templates, timing and a request id per call instead (System health).

FastAPI's interactive API docs are at /docs on the backend port when EXPOSE_API_DOCS=true (the local launch config sets it; it is off in production). The root endpoint reports docs_url. requirements-ml.txt adds the transformer stack (several GB) for USE_MOCK_MODELS=false; that mode exists but is untested.

5. Frontend

cd clinicalbrief-frontendnpm installnpm run dev

6. First user

Create a user in Supabase Auth. New accounts start as pending with no access (every endpoint answers 403). Grant a role from the CLI:

py -3.12 -m app.cli set-role you@example.com admin

7. Copilot (optional)

Install Ollama, pull the model, and set LLM_MODEL / LLM_BASE_URL in .env if needed. Only loopback model URLs and locally run models are accepted. Without the model, the Copilot falls back to labelled rule-based answers.

ollama pull qwen3.5py -3.12 -m app.cli ask <patient_id> "<question>"

Data comes from Synthea (synthetic, FHIR R4). data/raw/ is git-ignored.

py -3.12 -m app.cli discover <path>                         # what's in a folder, what will be imported or skippedpy -3.12 -m app.cli import synthea <path>         [--dry-run] [--limit N]py -3.12 -m app.cli runs                                    # import history with counts and rejected recordspy -3.12 -m app.cli process-notes --limit N                 # run the AI pipeline on unprocessed notespy -3.12 -m app.cli set-role <email> <role>py -3.12 -m app.cli flag-demo [--count 10] [--apply]        # choose the public demo patients (dry run by default)

• Record ids are derived from (source_system, table, source_id), so re-importing updates rows instead of duplicating them.
• Invalid source records are skipped and written to import_errors with a reason; the rest continues.
• An unexpected failure rolls back every data write and marks the run failed.
• Source values are never invented: unknown birth dates, statuses and codes stay NULL.

All paths are under /api/v1 and need a Supabase Bearer token. “Patient-scoped” means clinicians reach only patients assigned to them; “not yours” and “doesn't exist” both return 404, so ids can't be probed. Roles come from require_roles(...) in app/api/v1/deps.py.

Responses may carry X-Total-Count (full size of a limited list), X-Pending-Entities (AI findings awaiting review) and X-FHIR-Validation (the export check result).

The API enforces roles, and Postgres row-level security mirrors them for anything a browser could call directly with the publishable key: clinical tables are read-only to clients, users cannot change their own role, and clients cannot write audit entries. All writes go through the API. Roles are never taken from signup metadata.

The backend suite runs on SQLite, and again on a local Postgres (pgserver) with the real migrations and RLS applied, testing as the authenticated and anon roles. Tests use a fake model and never call Ollama.

cd clinicalbrief-backendpy -3.12 -m pytest tests               # SQLiteTEST_PG=1 py -3.12 -m pytest tests     # local Postgres (pgserver) with the real migrations and RLS applied

Frontend checks:

npx tsc --noEmitnpm run buildnpm audit --omit=dev

Git hooks: pre-commit and pre-push run a secret scan (database URLs with a real password, Supabase secret keys, private keys). pre-push then runs the Postgres suite, failing if any test is skipped so the RLS and schema-drift guards always run, and the frontend type check. Enable them once per clone:

git config core.hooksPath .githooks

No linter is configured yet, for the backend or the frontend.

• Honesty labels

  Every feature is marked Implemented, Prototype or Not built in the README.

• No fabricated metrics

  No accuracy figure is shown anywhere until it is measured on a labelled set. Rates on the governance page are shares of human decisions, not accuracy.

• Human review first

  AI output is never treated as fact until a person approves or edits it. The graph, FHIR export, Copilot structured answers and risk score use reviewed entities only.

The schema in migrations/*.sql is the source of truth; the ORM must match it, and a test fails on any drift.

Known gaps and planned work are tracked in one place each, so they are not repeated here.