# Osteo Report — CLAUDE.md Generated by /init-project. Single source of truth for Claude in this repo. Global rules : `~/.claude/CLAUDE.md` — this file extends or overrides them. --- ## Project overview Web app (SPA) for a veterinary osteopath. Captures the session report on an animal: fills practitioner/animal metadata, clicks anatomy zones on three schematic views (lateral left, lateral right, dorsal), creates clinical findings, exports to A4 PDF with the full report JSON embedded as a native PDF attachment so the PDF can be re-imported later to resume editing. Open-source planned (AGPL-3.0). Client-side only. --- ## Stack - Node ≥ 20.18 / npm 10 - React 19 + TypeScript 5.6 strict - Vite 6 - Tailwind 4 + shadcn/ui (Tailwind 4 canary mode) - motion 12 (framer-motion) - pdf-lib 1.17 (PDF generation + attachments) - Zod 3, Zustand 5 (persist), react-hook-form 7, react-router 7 - react-zoom-pan-pinch (gated to a modal overlay only) - Vitest + @testing-library/react + Playwright (e2e roundtrip) - ESLint 9 flat + Prettier 3 + Husky 9 + lint-staged 15 - Docker (multi-stage node → nginx:alpine) + Traefik labels commented --- ## Build commands ``` npm install npm run dev # vite dev server on :5173 npm run build # tsc -b && vite build npm run preview # vite preview on :4173 npm run test # vitest npm run test:e2e # playwright (needs `npx playwright install chromium` once) npm run lint npm run typecheck npm run format # Docker docker compose up --build ``` --- ## Folder structure ``` src/ main.tsx, App.tsx, vite-env.d.ts routes/ — HomeRoute, NewReportRoute, EditorRoute, NotFoundRoute editor/ — AnatomyCanvas, AnatomyView, ZoneSelection, FindingPanel, FindingEditor, ZoomOverlay, ConclusionPanel, ExportButton species/ types.ts, registry.ts equine/ — anatomy.ts, pathologies.ts, *.svg (full clinical data) chien,chat,lapin,bovin,chevre,ane,mouton,porc/ — stubs for later pdf/ — export.ts, import.ts, version.ts, render/* schema/ — report.ts, finding.ts, practitioner.ts (Zod) state/ — reportStore.ts (Zustand persist), selectors.ts components/ — Header, Footer, Brand, ui/ (shadcn) lib/ — cn, id, date, motion styles/ — globals.css, tokens.css i18n/ — fr.ts tests/ unit/ — vitest *.test.ts e2e/ — playwright roundtrip docs/ ARCHITECTURE.md, ADDING-A-SPECIES.md, ANATOMY-SVG-CONVENTION.md public/ favicon.svg Dockerfile, docker-compose.yml, nginx.conf .claude/ — tasks/, memory/, audits/ ``` --- ## Architecture - Single Zustand store = source of truth (`useReportStore`). `persist` middleware autosaves to localStorage under key `osteo-report-draft`. - Zod schemas in `src/schema/` define the wire format. TS types derived via `z.infer`. No manual duplication. - Each species ships its own pack `{ anatomy, pathologies }`, registered in `src/species/registry.ts`. The form lists ALL species; only those registered are usable (others are disabled with a "à venir" badge). MVP = equine only. - PDF export builds A4 portrait with `pdf-lib`, then `PDFDocument.attach(JSON, 'report.json')`. On import, the file is parsed, the `report.json` attachment is read, validated through `ReportSchema.safeParse`. If absent → `NO_ATTACHMENT` error shown to user. - The `react-zoom-pan-pinch` library is used ONLY inside `ZoomOverlay` (modal) to avoid click+pan event conflicts on the main SVG. - nginx serves the static SPA with strict CSP (`unsafe-inline` allowed for `style-src` only — needed by motion). --- ## Project conventions - Files: kebab-case folders, PascalCase components, camelCase utils. - Types from Zod: `type Foo = z.infer`. Never write a parallel interface. - Imports: absolute via `@/` (resolves to `src/`). - French strings: in `src/i18n/fr.ts` only. No hardcoded user-facing text in components. - One responsibility per component. Editor panels do NOT mutate store from JSX inline handlers — go through a store action. - Anatomy SVG layers: `#illustration` (non-interactive) + `#zones` (`data-zone="..."` clickable paths). See `docs/ANATOMY-SVG-CONVENTION.md`. --- ## Exceptions to global rules - None. Global rules in `~/.claude/CLAUDE.md` apply. - `noUncheckedIndexedAccess` is on — be explicit about possible `undefined` from array indexing. --- ## Key dependencies ``` react 19 — UI framework react-router 7 — client-side routing (3 routes) zustand 5 — state, with persist middleware zod 3 — runtime validation, source of types pdf-lib 1.17 — PDF build with file attachments react-hook-form 7 — form state react-zoom-pan-pinch — modal zoom for sub-zones motion 12 — animations (framer-motion lineage) date-fns — French date formatting nanoid — ID generation tailwindcss 4 — styling (CSS-config mode) shadcn/ui — base components (canary supports v4) lucide-react — icons vitest, @testing-library/react, playwright — tests ``` --- ## Workflow expectations - Read `.claude/memory/` registries at session start. - Plan in `.claude/tasks/TODO.md` before touching logic. - TDD for any non-trivial behavior: write test first, then make it pass. - Roundtrip test (`tests/unit/pdf.roundtrip.test.ts`) must stay green on every PR — it's the canary for breaking changes in the PDF format. - Never `npm install` a dep without naming it in this file's "Key dependencies" section. - No backend in MVP. If a task seems to need one, push it to Phase 2. - The pathology DB must cite sources. Adding entries without a source = blocker. - Anatomy illustrations and zone polygons are out of scope for code. Placeholders are acceptable until the artwork lands.