Files
faunosteo/CLAUDE.md
T

11 KiB
Raw Blame History

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

# 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)

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
    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:run before 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/pnpm on dev host. Add to PATH in shell profile.

Commit message convention

Conventional Commits format. Subject ≤72 chars, imperative mood, no trailing period. Allowed scopes: schema, store, anatomy, pdf, editor, home, new, ui, config, species, docker, docs, tests, chore.

Examples:

  • test(schema): cover Report version literal
  • feat(store): implement addObservation
  • feat(anatomy): parse data-bone-id from SVG