temetro/backend/CLAUDE.md

# CLAUDE.md

Guidance for Claude Code when working in `backend/`. See the root `../CLAUDE.md` for the project
vision and `README.md` here for run/setup instructions.

## What this is

The temetro API: **TypeScript + Express 5 + Postgres (Drizzle ORM)**, with authentication and
multi-tenant clinics via **Better Auth**. Serves the `../frontend` app. ESM (`"type": "module"`),
Node ≥ 20. This is its own git repo — commit changes here with the
`Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>` trailer.

## Commands

```bash
npm run dev          # tsx watch on http://localhost:4000
npm run build        # tsc -> dist/
npm run typecheck    # tsc --noEmit
npm run auth:generate  # Better Auth CLI -> src/db/schema/auth.ts (re-run after auth config changes)
npm run db:generate    # drizzle-kit: schema -> ./drizzle/*.sql migration
npm run db:migrate     # drizzle-kit: apply migrations (local dev)
npm run db:apply       # node dist/migrate.js — runtime migrator (used by Docker)
```

No test runner is configured. Verify by running the stack (`docker compose up`) and curling, or
`npm run dev` against a local Postgres. See `README.md`.

## Architecture

- **`src/auth.ts`** — the Better Auth config (the CLI auto-discovers it). Email/password +
  **username** plugin (staff sign in by username) and the organization plugin (clinics) with custom
  RBAC from **`src/lib/access.ts`** (`owner`/`admin`/`doctor`/`reception`/`pharmacy`/`lab`/`member`
  over `patient`/`appointment`/`prescription`/`task`/`lab` resources). `reception` has no
  `prescription` statement — it's scoped to scheduling + registration, and
  `src/services/patients.ts` redacts clinical fields for it. `pharmacy` has `prescription`
  read/write (no delete — `prescription:delete` is the full-clinician marker the frontend route
  gating probes); `lab` submits results via the `lab` statement (`POST
  /api/patients/:fileNumber/labs`) without `patient:write`. Mounted in `src/index.ts` via `toNodeHandler(auth)` at `/api/auth/*`.
- **`src/routes/staff.ts`** — admin-provisioned staff: `POST /api/staff` creates a user
  (`auth.api.signUpEmail`) + attaches them to the clinic (`auth.api.addMember`); `GET /api/staff`
  lists members with usernames. Replaces the old email-invitation flow. Gated by
  `requirePermission({ member: ["create"] })`.
- **Better Auth = the single source of RBAC.** Manage all permissions through Better Auth, not a
  custom layer. Authoritative references live as repo skills under
  `.claude/skills/{better-auth-best-practices,organization-best-practices,
  email-and-password-best-practices,better-auth-security-best-practices}` — consult them before
  changing `auth.ts`, `src/lib/access.ts`, or the auth schema.
- **`src/db/`** — `index.ts` is the Drizzle client (no schema passed; we use the core query builder).
  `schema/auth.ts` is **generated** by the Better Auth CLI; `schema/patients.ts` is hand-written and
  references the generated `organization`/`user` tables.
- **`src/services/patients.ts`** maps DB rows ⇆ the canonical `Patient` shape
  (`src/types/patient.ts`, mirrors `../frontend/lib/patients.ts`). **`src/routes/patients.ts`** is
  org-scoped CRUD, gated by **`src/middleware/auth.ts`** (`requireAuth` → `requireOrg` →
  `requirePermission`).
- **Other resources** follow the patients/notes pattern (schema → validation → types → service →
  org-scoped route): **appointments**, **prescriptions**, **tasks** (RBAC-gated like patients),
  plus **activity** (an audit log written best-effort from every resource route via
  `services/activity.ts`), **analytics** (computed aggregates), **messaging** (conversations /
  participants / messages) and **notifications** (per-recipient, auto-generated).
- **Real-time** lives in **`src/realtime.ts`** — a Socket.io server attached to the same HTTP server
  in `index.ts`; the handshake reuses Better Auth's `getSession`. Other modules push via
  `emitToUser` / `emitToConversation` (no direct socket import, so no circular deps).
- **`src/lib/email.ts`** — `sendEmail` logs links to the console when SMTP is unset.

## Gotchas / conventions

- **Schema generation order (circular bootstrap):** `auth.ts` → `db/index.ts` must NOT pull in the
  patient schema, so the Better Auth CLI can load `auth.ts` to (re)generate `schema/auth.ts`. After
  any auth/plugin change: `npm run auth:generate` → `npm run db:generate` → `npm run db:migrate`.
- **Express 5** needs a named wildcard: `app.all("/api/auth/*splat", …)`, and the Better Auth handler
  must be registered **before** `express.json()`.
- **Secure cookies** key off `BETTER_AUTH_URL` scheme (https), **not** `NODE_ENV` — otherwise login
  breaks over `http://localhost` in the production-mode Docker stack.
- **Rate limiting** needs a client IP; behind no proxy we backfill `x-forwarded-for` from the socket
  in `index.ts` so it still applies.
- **Env:** `src/env.ts` (zod) treats empty strings as unset (compose passes `${VAR:-}` as `""`) and
  has dev defaults so the CLIs can load the config offline.
- **Email verification is wired but NOT enforced** at sign-in
  (`emailAndPassword.requireEmailVerification: false` in `auth.ts`) — re-enable by flipping it to
  `true` (and route signup back to `/verify-email` in the frontend).
- Docker: migrations run on container start (`node dist/migrate.js`); `docker-compose.yml` exposes a
  configurable `POSTGRES_PORT` host port.

## AI chat

- **`src/routes/chat.ts`** — `POST /api/chat`, a tool-using agent (AI SDK v6 `streamText`)
  gated by `patient:read`. Providers resolve from the picked model id via
  **`src/services/ai/provider.ts`** (Anthropic / OpenAI / Gemini for API-key mode, or a
  local Ollama via the OpenAI-compatible endpoint). Tools (`src/services/ai/tools.ts`)
  reuse the patient service under the same role scoping and stream **real** record data to
  the client as custom data parts while the model sees only Veil-redacted results.
- **Veil** (`src/services/ai/veil.ts`) de-identifies PHI to tokens before external calls,
  resolves tokens on tool args, and rehydrates the final text (external mode runs
  non-streamed so the rehydrated text is correct). Local mode bypasses it.
- **AI config** lives in **`src/routes/ai.ts`** (`/api/ai/config`, `/test`, `/import`) over
  the `user_ai_settings` table; provider keys are encrypted with `src/lib/crypto.ts`
  (`AI_CREDENTIALS_KEY`). The migration **import** is gated behind a client approval step
  and re-validated server-side.

## Not built yet

The signing / patient-owned-storage / approval flow.