The file lived at the repo root, where Vite never bundles it (only index.html is the build entry). In production nginx fell through to the SPA index.html and React showed 'Page introuvable' at /pathology-editor.html. Moving it under public/ makes Vite copy it verbatim into dist/, so nginx serves it as a real static file. The /editors link (href=/pathology-editor.html) is unchanged — public/ is the web root. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
13 KiB
Faunosteo — 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 faunosteo .
# 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
│ └─ pathology-editor.html ← standalone JSON editor (served as static file)
├─ src/
│ ├─ app/
│ │ ├─ App.tsx ← root router
│ │ ├─ routes/{Home,NewReport,Editor,SvgEditor,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
│ │ │ └─ findings.ts
│ │ └─ species/
│ │ ├─ types.ts ← SpeciesManifest interface
│ │ ├─ registry.ts ← getSpecies(), getAllSpecies()
│ │ └─ equine/{index,vertebrae,pathologies}.{ts,json}
│ ├─ i18n/
│ │ ├─ types.ts ← Locale type + Dict type
│ │ ├─ fr.ts + en.ts ← translation dicts (flat key → string)
│ │ ├─ index.ts ← getDict(locale)
│ │ └─ useT.ts ← useT() hook (reads localeStore)
│ ├─ state/
│ │ ├─ reportStore.ts ← Zustand store
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
│ │ └─ practitionerCache.ts ← localStorage prefill
│ ├─ anatomy/
│ │ ├─ types.ts ← Bone, BoneCategory, BoneState
│ │ ├─ svgConvention.ts ← parseSvgBones()
│ │ ├─ svgLoader.ts ← loadSvg(), svgToPngDataUrl()
│ │ └─ labels.ts ← boneLabel(bone, locale, fallback)
│ ├─ components/
│ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip}.tsx
│ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx
│ │ ├─ observation/{ObservationList,ObservationCard,FindingsTreePicker,
│ │ │ VertebraPicker,SeveritySelector,
│ │ │ FreeTextFindingInput}.tsx
│ │ ├─ report/{ReportHeader,PractitionerForm,AnimalForm,
│ │ │ ConclusionPanel,NextAppointmentPicker}.tsx
│ │ └─ brand/{Brand,LanguageSwitcher}.tsx
│ ├─ pdf/
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng}.ts
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones}.ts
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
│ └─ 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
│ │ ├─ 2026-05-20-b3-i18n-fr-en-design.md
│ │ └─ 2026-05-22-pathology-editor-design.md
│ └─ superpowers/plans/
│ ├─ 2026-05-18-osteo-report-mvp.md
│ └─ 2026-05-20-b3-i18n-fr-en.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-anno-opens-detail → DetailModal (loads detail SVG)
→ else → updateObservation() in store
PDF export
→ exportReportToPdf(report, { locale })
→ pdf-lib PDFDocument
→ embedFonts (Helvetica body + TimesRoman heading — WinAnsi StandardFonts; TTF Inter/Fraunces planned)
→ 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: bilingual FR/EN — all user-facing text goes through the i18n system (see below)
- Code: English (variable names, function names, comments, docs)
- Never mix: no French variable names, no raw French/English string literals in JSX — use
useT()
i18n
- All user-facing strings live in
src/i18n/fr.tsandsrc/i18n/en.ts(flatRecord<string, string>) - Key convention:
<area>.<key>— e.g.common.cancel,home.new_report.title,pdf.subject - Both dicts must share the exact same key set; a key missing in one dict logs a warning in DEV
- Get the translate function in any component:
const t = useT()thent('common.cancel') src/state/localeStore.tsholds currentLocale('fr' | 'en'), persisted tolocalStoragekeyosteo:locale; default: navigator-detectedfr/en, or'fr'if no match- Finding leaf labels (zone names shown in PDF) are resolved at export time via SVG
data-anno-name-fr/data-anno-name-enattributes — not from the dict - PDF static labels (section headings, metadata) come from the dict via
getDict(locale)inexportReportToPdf
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-anno-id, data-anno-name-fr, data-anno-name-en, data-anno-category
- SvgConventionError thrown on any missing required attribute
- Never rely on element id or className for click targeting — always data-anno-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 StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g.
(!)instead of⚠).
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.
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, i18n, docker, docs, tests, chore.
Examples:
test(schema): cover Report version literalfeat(store): implement addObservationfeat(anatomy): parse data-anno-id from SVG