Files
faunosteo/CLAUDE.md
T
Bastien ChanotandClaude Opus 4.6 2d6ed809e2 chore: rename Zoosteo → Faunosteo across entire project
Brand strings, config defaults, i18n dicts, PDF attachment metadata,
HTML titles, Docker container name, package name, repo URLs, deploy
paths, and all documentation updated. Git remote switched to
faunosteo.git. Domain URLs (zoosteo.fr) preserved — DNS update is
separate. 155/155 tests green.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-22 21:44:21 +02:00

335 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```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: 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
```bash
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
```bash
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,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}.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, pathology-editor.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 <div>ComponentName placeholder</div>
- 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`