Skeleton for Osteo Report MVP. Build passes, 7 smoke tests green, real Horse.svg + Horse_head.svg in public/species/equine/. Zod schemas are the contract; store/anatomy/pdf modules are typed stubs throwing "not implemented" awaiting implementation. Spec: docs/superpowers/specs/2026-05-18-osteo-report-mvp-design.md Plan: docs/superpowers/plans/2026-05-18-osteo-report-mvp.md (23 phases, ~70 TDD tasks) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
10 KiB
10 KiB
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-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
# 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
# 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
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
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)
- 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 ComponentName placeholder
- Replace stub body entirely when implementing — no partial edits on stubs
Exceptions to global rules
- React SPA: explicit exception — this is a practitioner tool, not a public website. No indexing needed. SPA is correct. (See BDR-001)
- No API versioning: no backend, no API routes. Section N/A.
- 80-char line limit: relaxed to 100 for TypeScript generics and long Zod chains.
Key dependencies
| Package | Purpose |
|---|---|
| react 19 | UI framework, automatic memo + concurrent rendering |
| react-dom 19 | DOM renderer |
| react-router-dom 7 | Client-side routing (BrowserRouter) |
| vite 7 | Build tool, HMR, ESM-native |
| @vitejs/plugin-react-swc | Fast React transform via SWC |
| typescript 5 | Type safety, strict mode |
| tailwindcss 4 | CSS-first utility framework |
| zustand 5 | Lightweight global state |
| zod 3 | Schema validation + type inference |
| pdf-lib 1.17 | Pure-JS PDF generation + native attachments |
| canvg 4 | SVG → Canvas rasterization for PDF |
| motion 11 | Animations (modals, toasts, observation cards) |
| vitest 3 | Test runner |
| happy-dom | DOM environment for tests |
| @testing-library/react | Component testing utilities |
| @testing-library/jest-dom | Custom DOM matchers |
| eslint 9 | Linting (flat config) |
| prettier 3 | Code formatting |
Workflow expectations
- Run
pnpm typecheck && pnpm test:runbefore every commit. - Domain schema changes (domain/schema/*.ts) require updating all callers + bumping version if breaking.
- SVG convention changes require updating docs/ANATOMY-SVG-CONVENTION.md first.
- Never modify anatomy SVGs in public/species/ — they are source assets from the user.
- Pathology DB entries must be source-cited before commit; client review required for MVP batch.
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then pako decompression.
- pnpm binary:
~/.local/share/pnpm/bin/pnpmon dev host. Add to PATH in shell profile.