CLAUDE.md

1# OpenLeukemia Claude Memory
2 
3OpenLeukemia is a patient-centered platform for organizing leukemia-related medical data, tracking changes over time, extracting structured information from documents, and explaining validated model outputs in plain language.
4 
5## Stack
6 
7- Frontend: React 19, TypeScript, Vite, Vitest, ESLint
8- Platform: Supabase Auth, Postgres, Storage, RLS, Edge Functions
9- AI service: Python 3.12, FastAPI, Pydantic, Uvicorn
10- Package manager: npm workspaces for `frontend`; Python virtualenv for `ai-service`
11 
12## Core Rules
13 
14- Patient data belongs to the patient.
15- Registration is not blanket consent.
16- Consent must be separate, explicit, auditable, and revocable.
17- AI may summarize, extract, and explain; it must not diagnose, recommend treatment, or make urgent clinical judgments.
18- Treat LLM extraction as candidate data until validated or confirmed.
19- Prefer Supabase for routine product workflows; use `ai-service/` for Python, ML, OCR, extraction, parsing, and heavier compute.
20 
21## Commands
22 
23Frontend, from repo root:
24 
25```sh
26npm install
27npm --workspace frontend run dev
28npm run lint:frontend
29npm run typecheck:frontend
30npm test --workspace frontend
31npm --workspace frontend run build
32```
33 
34AI service, from `ai-service/`:
35 
36```sh
37python -m venv .venv
38python -m pip install -e ".[dev]"
39python -m uvicorn app.main:app --reload
40python -m ruff check .
41python -m pytest
42python -m mypy app
43```
44 
45## Working Style
46 
47- Read nearby code and docs before editing.
48- Make minimal, focused changes and preserve existing architecture.
49- Do not rewrite unrelated files or add dependencies without clear need.
50- Use typed models and structured parsing instead of ad hoc string handling.
51- Keep patient-facing text calm, plain, and non-diagnostic.
52- Run the most relevant checks after edits when practical; otherwise name the skipped check.
53- Directory-specific `CLAUDE.md` files add local rules when working in those subtrees.
54 
55## Claude Workflow Patterns
56 
57- Optimize for the user's intended outcome, not a literal step list; find the relevant files yourself when the request is behavioral.
58- For unfamiliar code, first explain architecture, data flow, and dependencies before editing.
59- Before deleting or broadly refactoring, identify callers, downstream effects, and the files likely to change.
60- For multi-file or risky changes, plan the touched files and verification path before editing.
61- Match existing patterns by reading a nearby implementation the project already accepts.
62- When the user provides an error, log, screenshot, plan output, issue, or file, treat that artifact as primary evidence.
63- Build self-check loops into implementation work: write/run tests, build, lint, typecheck, render, compare, or otherwise verify.
64- Use measurable targets when available: coverage threshold, latency goal, bundle size, visual delta, or exact API behavior.
65- If the user corrects the same mistake or asks to preserve a convention, turn that correction into a durable `CLAUDE.md` rule.
66