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 directory is the project root; the actual apps live in subdirectories.

Status: the backend is now 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 (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/ — 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. It is also its own git repository.
• landing-page/ — the marketing landing page. A standalone copy of frontend/ (same customized Next.js stack) with the landing sections in components/landing/.
• 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. Its own git repository.
• database/, docs/ — still empty placeholders.
• landing-page/ — see above; unchanged, still UI-only marketing.

frontend/, landing-page/, 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.

Running the stack

From backend/: cp .env.example .env (set BETTER_AUTH_SECRET; set POSTGRES_PORT if 5432 is already in use), then docker compose up → frontend :3000, backend :4000, Postgres. See backend/README.md. 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 (per-folder git)

Each top-level folder is its own git repository (frontend/, landing-page/, backend/, database/, docs/); there is intentionally no git repo at this root.

Commit after every change. Whenever you modify files in a folder that contains a .git, finish the task by committing those changes in that folder (git -C <folder> add -A && git -C <folder> commit), so each folder's history tracks its own changes. Keep each commit scoped to one folder — a change spanning two folders is two commits. End commit messages with the Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> trailer.

Customized Next.js (applies to both apps)

Both apps run a customized Next.js 16 whose APIs/conventions differ from public docs. Before writing Next.js code, read the relevant guide under <app>/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.