# 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 | 24 LTS (`.nvmrc`, `engines` >=22.12 <25) | | Package manager | pnpm | 10.13.1 (`packageManager`, root devDependency) | | 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 | native Image/canvas (no dependency) | — | | Animation | motion | 11 | | Tests | vitest + happy-dom + @testing-library/react | 3.x | | Deploy | Docker multi-stage → nginx:alpine | — | --- ## Build commands pnpm workspace: `apps/app` = the private application, `packages/` empty for now (see `docs/development/WORKSPACE.md`). Every command below runs from the repository root and delegates to the packages. ```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 faunosteo . # Run with compose (reads .env for APP_* vars) docker compose up --build # Stop docker compose down ``` Note: no global pnpm needed. `corepack enable` once (reads `packageManager`), or call `corepack pnpm `. Root scripts resolve `node_modules/.bin/pnpm`. --- ## Test commands ```bash pnpm test:run # vitest run — all tests, single pass, CI-safe pnpm test # vitest watch — dev loop ``` Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in `apps/app/tests/fixtures/`. Setup: `apps/app/tests/setup.ts` imports @testing-library/jest-dom. Characterisation suite: files prefixed `char.`. --- ## Lint / format commands ```bash pnpm lint # ESLint 9 flat config — max-warnings 0 pnpm format # Prettier write ``` --- ## Folder structure ``` faunosteo/ ├─ apps/app/ ← @faunosteo/app (everything below until packages/) ├─ 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,Editors,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() │ │ └─ 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,LateralityPicker, │ │ │ FreeTextFindingInput}.tsx │ │ ├─ report/{ReportHeader,PractitionerForm,AnimalForm, │ │ │ ConclusionPanel,NextAppointmentPicker}.tsx │ │ └─ brand/{Brand,AppHeader,Footer,LanguageSwitcher}.tsx │ ├─ pdf/ │ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts │ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.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 │ ├─ faunosteo-audit/ ← audit of the current system (frozen at 83e40af) │ ├─ development/ ← SaaS implementation plan, WORKSPACE.md │ └─ history/superpowers/{specs,plans}/ ← 2026-05 design records (docs/superpowers is purged by gitflow finish) ├─ eslint.config.js, index.html, package.json (@faunosteo/app) ├─ tsconfig*.json, vite.config.ts, vitest.config.ts │ (end of apps/app) ├─ packages/README.md ← future shared packages (none yet) ├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker ├─ .claude/{tasks/TODO.md,memory/,audits/} ├─ Dockerfile, docker-compose.yml, docker/ ├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json ├─ package.json (workspace root), pnpm-workspace.yaml, pnpm-lock.yaml ├─ CLAUDE.md, README.md, DEPLOY.md, CHANGELOG.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`) - Key convention: `.` — 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 = 2 (v1 attachments rejected at import with a typed error); future breaking changes → version 3 ### 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 | | 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 DecompressionStream inflation. - Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install. ## 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`, `app`, `workspace`, `ci`. Examples: - `test(schema): cover Report version literal` - `feat(store): implement addObservation` - `feat(anatomy): parse data-anno-id from SVG`