Files
faunosteo/CLAUDE.md
T
ZenQuality a115e785a7 chore: initial scaffold
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.
2026-05-17 06:43:11 +02:00

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). 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<typeof FooSchema>. 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.