temetro/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

`temetro` — an **open-source** clinical tool that acts as an **AI middleman** between clinicians and
patient data. Clinicians use a natural-language AI chat to retrieve and organize patient information,
displayed as rich record cards.

The distinguishing idea is a **patient-owned data model**. Instead of (or alongside) living in a
doctor's own database, a patient's record can be stored on the **patient's own device**. When a
clinician adds or changes data, they **sign** it (blockchain-style); the change is written to the
patient's record and **cannot be modified until the patient approves it** through a companion app.
temetro can also **read existing patient databases** and present them in the same organized card UI.

This repository is a **monorepo**: the `frontend/` and `backend/` apps live side by side in one git
repository (published as `temetro`).

> **Status:** the **backend is built**. `backend/` is a TypeScript + Express + Postgres API
> (Drizzle ORM) with authentication and multi-tenant clinics via **Better Auth**, plus an
> **org-scoped patient records API**. The `frontend/` chat is **wired to it**: real auth
> (login/signup/reset/onboarding), route protection, clinic switching, and patient data fetched
> over the API — the old in-memory fixture is gone (`frontend/lib/patients.ts` now calls the backend).
>
> **Still vision, not built:** the patient companion app and the blockchain-style **signing /
> patient-owned storage / approval** flow. The AI chat itself is still **mock replies** (no LLM
> call yet — a `/chat` endpoint is the next planned step). Email verification is wired but
> currently **not enforced** at sign-in (see `backend/CLAUDE.md`).

## Layout

`frontend/` and `backend/` were previously separate per-folder git repos; they have been **merged
into this single monorepo with full history of both preserved**.

The marketing **landing page is not in this monorepo** — it lives in the sibling Desktop folder
`../temetro/landing-page` (`/Users/khalidabdi/Desktop/temetro/landing-page`), right next to the
`../temetro/docs` site. It is **its own git repository** (a Next.js app with the marketing
`components/landing/`); edit and commit it there, separately from this repo.

- **`frontend/`** — the Next.js product app (the AI chat UI). This is where almost all current work
  happens. **It has its own `CLAUDE.md`** — read `frontend/CLAUDE.md` for the stack, commands,
  architecture, and gotchas.
- **`backend/`** — the TypeScript + Express + Postgres API (Drizzle ORM + Better Auth). Built and
  Dockerised. **Has its own `CLAUDE.md`** (and `README.md`) — read it for the auth/schema workflow
  and gotchas.

`frontend/` and `backend/` are **independent apps**, each with its own `package.json` /
`node_modules`. Run `npm` commands from inside the relevant app directory, not from this root.

## Documentation (very important)

The **project documentation lives outside this repo**, in the sibling Desktop folder
`../temetro/docs` (`/Users/khalidabdi/Desktop/temetro/docs`) — a Fumadocs (Next.js) site with
user guides (`content/docs/guides/`), an API reference (`content/docs/api/`), admin docs, and a
roadmap (`content/docs/roadmap.mdx`). It is its own git repository.

**Whenever you make a significant change here — a new feature, endpoint, page, or behavior
change — update the affected docs pages in the same work session** so the documentation stays
accurate (e.g. a new backend route needs an `content/docs/api/*.mdx` entry; a UI feature belongs
in the matching guide; status changes belong in the roadmap). Commit docs changes inside that
repo, separately from this one.

## Running the stack

From `backend/`: ensure a `.env` exists (`cp .env.example .env`, then set `BETTER_AUTH_SECRET` via
`openssl rand -base64 32`), then `docker compose up --build` → frontend :3000, backend :4000,
Postgres. Compose builds the sibling `../frontend` app, which works because they remain siblings in
the monorepo. See `backend/README.md`.

> **Port note:** if another Postgres already holds host port 5432, set `POSTGRES_PORT` (e.g. `5433`)
> in `backend/.env` — the app still talks to Postgres internally on `db:5432`; only the published
> host port changes.

For local dev without Docker, run `npm run dev` in `backend/` and `frontend/` separately (the
frontend reads `NEXT_PUBLIC_API_URL`, default `http://localhost:4000`).

## Version control (single monorepo)

This root is **one git repository** (`temetro`). The old per-folder `.git` repos are gone —
`frontend/` and `backend/` are plain subdirectories now.

**Commit after every change.** When you finish a task, commit from the repo root
(`git add -A && git commit`). Keep each commit focused on one logical change, and prefix the subject
with the area when useful (e.g. `frontend:` / `backend:`). End commit messages with the
`Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>` trailer.

`.env` files are git-ignored (only `.env.example` is tracked) — never commit real secrets.

## Customized Next.js (frontend)

The `frontend/` app runs a **customized Next.js 16** whose APIs/conventions differ from public docs.
Before writing Next.js code, read the relevant guide under
`frontend/node_modules/next/dist/docs/01-app/`.

## Root tooling

- `.mcp.json` registers the **shadcn MCP server**, and the root `package.json` pins the `shadcn`
  CLI — used to browse/add registry components into the apps. There is nothing to build or run at
  this root level.