Remote moved to git.bchanot.fr/bchanot/zoosteo.git; brand strings
and production URL updated to match new identity.
- package.json: name → zoosteo
- src/config/env.ts: AppConfig DEFAULTS → "Zoosteo"
- docker/entrypoint.sh: APP_*_NAME fallbacks → "Zoosteo"
- src/i18n/{fr,en}.ts: import error message + PDF title prefix
- src/pdf/attachment.ts: embedded description metadata "state v2"
- index.html: <title> fallback
- scripts/scaffold-species.mjs: console banner
- tests/unit/components.Brand.test.tsx: regex
- README.md, CLAUDE.md, CHANGELOG.md, docs/ADDING-A-SPECIES.md:
brand headings + intro lines
- DEPLOY.md: env defaults table + osteo.example.com → zoosteo.fr
(clone URL, paths, certbot, curl, container name references)
PDF attachment FILENAME 'osteo-report.json' and the startsWith
contract in src/pdf/attachment.ts:35,40 are preserved — changing
them would break PDF import for every PDF already exported by the
app. docs/superpowers/** and .claude/audits/** left unchanged as
historical records.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
334 lines
12 KiB
Markdown
334 lines
12 KiB
Markdown
# Zoosteo — 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 zoosteo .
|
||
|
||
# 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,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}.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
|
||
│ │ └─ 2026-05-20-b3-i18n-fr-en-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 <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`
|