Generated by /init-project. React 19 + TS strict + Vite 6 + Tailwind 4 + shadcn/ui + motion + pdf-lib + Zod + Zustand + react-router 7. Empty skeleton, no business logic. Docker multi-stage + nginx + Traefik labels commented. AGPL-3.0-or-later.
5.7 KiB
5.7 KiB
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).persistmiddleware autosaves to localStorage under keyosteo-report-draft. - Zod schemas in
src/schema/define the wire format. TS types derived viaz.infer. No manual duplication. - Each species ships its own pack
{ anatomy, pathologies }, registered insrc/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, thenPDFDocument.attach(JSON, 'report.json'). On import, the file is parsed, thereport.jsonattachment is read, validated throughReportSchema.safeParse. If absent →NO_ATTACHMENTerror shown to user. - The
react-zoom-pan-pinchlibrary is used ONLY insideZoomOverlay(modal) to avoid click+pan event conflicts on the main SVG. - nginx serves the static SPA with strict CSP (
unsafe-inlineallowed forstyle-srconly — needed by motion).
Project conventions
- Files: kebab-case folders, PascalCase components, camelCase utils.
- Types from Zod:
type Foo = z.infer<typeof FooSchema>. Never write a parallel interface. - Imports: absolute via
@/(resolves tosrc/). - French strings: in
src/i18n/fr.tsonly. 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). Seedocs/ANATOMY-SVG-CONVENTION.md.
Exceptions to global rules
- None. Global rules in
~/.claude/CLAUDE.mdapply. noUncheckedIndexedAccessis on — be explicit about possibleundefinedfrom 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.mdbefore 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 installa 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.