# Osteo Report — CLAUDE.md # Generated by scaffolder 2026-05-18. Single source of truth for Claude in this repo. # Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them. --- ## Project overview Single-praticien French web app for veterinary osteopathy bilans on animal anatomy SVGs. Practitioner clicks anatomical zones, builds observations with pathologies/severity, writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native attachment so importing it restores the session for a follow-up. Static SPA, no backend, no auth. Deployed via Docker + nginx on Scaleway VPS. MVP species: equine only. Open-source MIT. --- ## Stack | Concern | Choice | Version | |---|---|---| | Runtime | Node.js | 20 | | Package manager | pnpm | >=9 (11.x on host) | | Build | Vite + @vitejs/plugin-react-swc | 7.x | | UI | React | 19 | | Language | TypeScript strict | 5.x | | Styling | Tailwind CSS v4 CSS-first (no postcss config) | 4.x | | State | Zustand | 5 | | Validation | Zod | 3 | | PDF | pdf-lib | 1.17 | | SVG raster | canvg | 4 | | Animation | motion | 11 | | Tests | vitest + happy-dom + @testing-library/react | 3.x | | Deploy | Docker multi-stage → nginx:alpine | — | --- ## Build commands ```bash # Development pnpm dev # Production build (typecheck + vite build) pnpm build # Type-check only (no emit) pnpm typecheck # Preview production build pnpm preview # Tests (watch) pnpm test # Tests (CI / single run) pnpm test:run # Lint (0 warnings allowed) pnpm lint # Format pnpm format ``` ## Docker commands ```bash # Build image docker build -t osteo-report . # Run with compose (reads .env for APP_* vars) docker compose up --build # Stop docker compose down ``` Note: pnpm binary at `~/.local/share/pnpm/bin/pnpm` on dev host (corepack broken). Add it to PATH: `export PATH="$HOME/.local/share/pnpm/bin:$PATH"`. --- ## Test commands ```bash pnpm test:run # vitest run — all tests, single pass, CI-safe pnpm test # vitest watch — dev loop ``` Test files live in `tests/unit/*.test.ts` and `tests/unit/*.test.tsx`. Setup: `tests/setup.ts` imports @testing-library/jest-dom. --- ## Lint / format commands ```bash pnpm lint # ESLint 9 flat config — max-warnings 0 pnpm format # Prettier write ``` --- ## Folder structure ``` osteo/ ├─ public/ │ └─ species/equine/{Horse,Horse_head}.svg ← real anatomy SVGs ├─ src/ │ ├─ app/ │ │ ├─ App.tsx ← root router │ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx │ │ └─ providers/ConfigProvider.tsx ← AppConfig context │ ├─ config/env.ts ← runtime config resolution │ ├─ domain/ │ │ ├─ schema/ ← Zod schemas (source of truth) │ │ │ ├─ report.ts │ │ │ ├─ observation.ts │ │ │ ├─ practitioner.ts │ │ │ ├─ animal.ts │ │ │ └─ pathology.ts │ │ └─ species/ │ │ ├─ types.ts ← SpeciesManifest interface │ │ ├─ registry.ts ← getSpecies(), getAllSpecies() │ │ └─ equine/{index,vertebrae,pathologies}.ts │ ├─ state/ │ │ ├─ reportStore.ts ← Zustand store │ │ └─ practitionerCache.ts ← localStorage prefill │ ├─ anatomy/ │ │ ├─ types.ts ← Bone, BoneCategory, BoneState │ │ ├─ svgConvention.ts ← parseSvgBones() │ │ └─ svgLoader.ts ← loadSvg(), svgToPngDataUrl() │ ├─ components/ │ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip,Toast}.tsx │ │ ├─ canvas/{AnatomyCanvas,DetailModal,ZoneTooltip}.tsx │ │ ├─ observation/{ObservationList,ObservationCard,ObservationEditor, │ │ │ PathologyPicker,VertebraPicker,SeveritySelector, │ │ │ FreeTextPathologyInput}.tsx │ │ ├─ report/{ReportHeader,PractitionerForm,AnimalForm, │ │ │ ConclusionPanel,NextAppointmentPicker}.tsx │ │ └─ brand/Brand.tsx │ ├─ pdf/ │ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts │ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng}.ts │ ├─ lib/{dates,id,assert}.ts │ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first │ └─ main.tsx ├─ tests/ │ ├─ setup.ts │ └─ unit/*.test.ts ├─ docker/ │ ├─ entrypoint.sh ← injects env.js at container start │ └─ nginx.conf ← SPA fallback + PORT envsubst ├─ docs/ │ ├─ ANATOMY-SVG-CONVENTION.md ← SVG data-* contract │ ├─ ADDING-A-SPECIES.md │ ├─ PDF-FORMAT.md │ └─ superpowers/specs/ │ └─ 2026-05-18-osteo-report-mvp-design.md ├─ .claude/{tasks/TODO.md,memory/,audits/} ├─ Dockerfile, docker-compose.yml ├─ .env.example, .editorconfig, .nvmrc, .prettierrc.json ├─ eslint.config.js, index.html ├─ package.json, tsconfig*.json ├─ vite.config.ts, vitest.config.ts ├─ CLAUDE.md, README.md, LICENSE ``` --- ## Architecture ``` User interaction → React routes (BrowserRouter) → Zustand store (reportStore) → Components read store via selectors (no prop drilling) SVG interaction → AnatomyCanvas fetches SVG text via loadSvg() → parseSvgBones() walks DOM → Bone map → delegated click listener → getBoneIdFromEvent() → if spine-zone → VertebraPicker modal → if data-opens-detail → DetailModal (loads detail SVG) → else → updateObservation() in store PDF export → exportReportToPdf(report) → pdf-lib PDFDocument → embedFonts (Inter body + Fraunces heading) → for each observation: addObservationPage (rasterize SVG → PNG) → addConclusionPage → attachReportJson (native EmbeddedFiles) → Uint8Array → browser download PDF import → importReportFromPdf(bytes) → extractReportJson → Zod validate → hydrateReport() → navigate /editor Runtime config → Docker entrypoint writes env.js (window.__APP_CONFIG__) → index.html loads env.js before bundle → src/config/env.ts reads window.__APP_CONFIG__ → VITE_APP_* → defaults → ConfigProvider exposes via React context ``` --- ## Project conventions ### Language split - UI strings: French (labels, placeholders, error messages, toasts) - Code: English (variable names, function names, comments, docs) - Never mix: no French variable names, no English labels in JSX ### Identity strings - NEVER hardcode APP_SITE_NAME, APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE - Always read from ConfigProvider via useConfig() - src/config/env.ts is the only place with defaults ### SVG convention - docs/ANATOMY-SVG-CONVENTION.md is the source of truth - Every clickable element must have: data-bone-id, data-bone-fr, data-bone-en, data-category - SvgConventionError thrown on any missing required attribute - Never rely on element id or className for click targeting — always data-bone-id ### Schemas - domain/schema/*.ts are the data contracts — never change without bumping version - All user-provided data goes through Zod parse before hitting the store - ReportSchema.version = 1 for MVP; future breaking changes → version 2 ### Stores - No direct store mutation outside Zustand actions - No business logic in components — delegate to store actions - sessionStorage key: osteo:draft (auto-saved on every observation change) - localStorage key: osteo:lastPractitioner (practitioner prefill cache) ### PDF - A4 portrait: 595.28 × 841.89 pt - No raw URLs in PDF output — abbreviated citations only - JSON attachment filename must start with osteo-report - Fonts are TTF (pdf-lib limitation — no woff2) ### Pathology DB - All entries must pass PathologySchema.parse() - Each entry needs ≥1 source with citation - boneIds: [] = all zones; speciesIds: [] = all species - Source types: manual | journal | database | web ### Component stubs - Scaffold stubs render