Files
Bastien ChanotandClaude Opus 4.8 2803cf7c7d fix(editor): serve pathology-editor.html from public/ so it ships to dist
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>
2026-06-13 23:41:53 +02:00

13 KiB
Raw Permalink Blame History

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 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.ts and src/i18n/en.ts (flat Record<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() then t('common.cancel')
  • src/state/localeStore.ts holds current Locale ('fr' | 'en'), persisted to localStorage key osteo:locale; default: navigator-detected fr/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-en attributes — not from the dict
  • PDF static labels (section headings, metadata) come from the dict via getDict(locale) in exportReportToPdf

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)

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 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: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, i18n, docker, docs, tests, chore.

Examples:

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