Skeleton for Osteo Report MVP. Build passes, 7 smoke tests green, real Horse.svg + Horse_head.svg in public/species/equine/. Zod schemas are the contract; store/anatomy/pdf modules are typed stubs throwing "not implemented" awaiting implementation. Spec: docs/superpowers/specs/2026-05-18-osteo-report-mvp-design.md Plan: docs/superpowers/plans/2026-05-18-osteo-report-mvp.md (23 phases, ~70 TDD tasks) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
# Osteo Report — 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 osteo-report .
|
||
|
||
# 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
|
||
│ │ │ └─ pathology.ts
|
||
│ │ └─ species/
|
||
│ │ ├─ types.ts ← SpeciesManifest interface
|
||
│ │ ├─ registry.ts ← getSpecies(), getAllSpecies()
|
||
│ │ └─ equine/{index,vertebrae,pathologies}.ts
|
||
│ ├─ state/
|
||
│ │ ├─ reportStore.ts ← Zustand store
|
||
│ │ └─ practitionerCache.ts ← localStorage prefill
|
||
│ ├─ anatomy/
|
||
│ │ ├─ types.ts ← Bone, BoneCategory, BoneState
|
||
│ │ ├─ svgConvention.ts ← parseSvgBones()
|
||
│ │ └─ svgLoader.ts ← loadSvg(), svgToPngDataUrl()
|
||
│ ├─ components/
|
||
│ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip,Toast}.tsx
|
||
│ │ ├─ canvas/{AnatomyCanvas,DetailModal,ZoneTooltip}.tsx
|
||
│ │ ├─ observation/{ObservationList,ObservationCard,ObservationEditor,
|
||
│ │ │ PathologyPicker,VertebraPicker,SeveritySelector,
|
||
│ │ │ FreeTextPathologyInput}.tsx
|
||
│ │ ├─ report/{ReportHeader,PractitionerForm,AnimalForm,
|
||
│ │ │ ConclusionPanel,NextAppointmentPicker}.tsx
|
||
│ │ └─ brand/Brand.tsx
|
||
│ ├─ pdf/
|
||
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
|
||
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng}.ts
|
||
│ ├─ lib/{dates,id,assert}.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
|
||
├─ .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-opens-detail → DetailModal (loads detail SVG)
|
||
→ else → updateObservation() in store
|
||
|
||
PDF export
|
||
→ exportReportToPdf(report)
|
||
→ pdf-lib PDFDocument
|
||
→ embedFonts (Inter body + Fraunces heading)
|
||
→ 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: French (labels, placeholders, error messages, toasts)
|
||
- Code: English (variable names, function names, comments, docs)
|
||
- Never mix: no French variable names, no English labels in JSX
|
||
|
||
### 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-bone-id, data-bone-fr, data-bone-en, data-category
|
||
- SvgConventionError thrown on any missing required attribute
|
||
- Never rely on element id or className for click targeting — always data-bone-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 TTF (pdf-lib limitation — no woff2)
|
||
|
||
### 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.
|