# Osteo Report — MVP Architecture Spec Date: 2026-05-18 Status: Approved at validation gate #1. ## Purpose Web app for veterinary osteopaths — any praticien who wants to use it — to write session bilans on animal anatomy. The praticien selects a species, clicks anatomical zones on an SVG schematic to build clinical observations (groups of zones sharing one problem), attaches pathologies (curated DB + free-text) and severity per observation, writes a conclusion + recommendations + next RDV, and exports the whole report as a self-contained A4 PDF whose JSON state is carried as a native PDF attachment. Re-importing the PDF restores the state for a follow-up. Multi-species by architecture. v1 ships data for the **horse** (équin) only. Adding **dog, cat, goat, cow, pig, rabbit, donkey, sheep** later is a pure data drop: convention-compliant SVG + manifest entry + (eventually) pathology file under `src/domain/species//`. No code changes required. Static SPA, no backend, no auth, no analytics in v1 — the PDF is the only durable artifact. Deployed as a Docker image serving nginx behind a host nginx reverse proxy on Scaleway VPS. Identity strings (site name, brand, footer) come from env vars, never hardcoded. Open-source (MIT). v1 data set: equine. v1.1+ data sets: chien, chat, chèvre, vache, cochon, lapin, âne, mouton. Phase 2 also adds multi-praticien accounts + server-side persistence on the same data contract. ## Stack | Concern | Choice | Why | |---|---|---| | Build | Vite 7 + @vitejs/plugin-react-swc | Fast HMR, ESM-native, no Webpack tax. | | UI | React 19 + TypeScript 5 strict | Editor complexity warrants components; React 19's automatic memo + concurrent rendering. | | Styling | Tailwind v4 (CSS-first config) + design tokens in CSS | No PostCSS config, design tokens via @theme. | | State | Zustand 5 | Lighter than Redux, simpler than Context for editor; selectors avoid re-render storms. | | Validation | Zod 3 | Mirrors persisted JSON schema, gives import-time errors. | | PDF | pdf-lib 1.17 | Pure-JS, supports native PDF attachments via `attach()`. | | SVG raster | canvg 4 → canvas → PNG → `embedPng` | A4 print quality at 2× scale. | | Animation | motion 11 | Modal transitions, toasts, observation cards. | | Tests | vitest 3 + happy-dom + RTL | Unit-first; no e2e for MVP. | | Tooling | ESLint 9 flat config, Prettier, pnpm 9, Node 20 | Modern defaults. | | Deploy | Multi-stage Docker → nginx:alpine | Static dist served; entrypoint injects env into runtime config. | ## Folder tree ``` osteo/ ├─ public/species/equine/{Horse,Horse_head}.svg ├─ src/ │ ├─ app/{App,routes/{Home,NewReport,Editor,NotFound}Route,providers/ConfigProvider}.tsx │ ├─ config/env.ts │ ├─ domain/ │ │ ├─ schema/{report,observation,practitioner,animal,pathology}.ts │ │ └─ species/{registry,types,equine/{index,vertebrae,pathologies}}.ts │ ├─ state/{reportStore,practitionerCache}.ts │ ├─ anatomy/{svgLoader,svgConvention,types}.ts │ ├─ 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,import,attachment,fonts}.ts + pdf/render/{header,footer,observationPage,conclusionPage,svgToPng}.ts │ ├─ lib/{dates,id,assert}.ts │ ├─ styles/{index,tokens}.css │ └─ main.tsx ├─ tests/unit/*.test.ts + tests/setup.ts ├─ docs/{ANATOMY-SVG-CONVENTION,ADDING-A-SPECIES,PDF-FORMAT}.md + docs/superpowers/specs/ ├─ .claude/{tasks/TODO.md,memory/{decisions,learnings,blockers,journal,evals}.md,audits/.gitkeep} ├─ Dockerfile, docker-compose.yml, nginx.conf ├─ .env.example, .editorconfig, .nvmrc, .prettierrc.json, .gitignore, .dockerignore ├─ eslint.config.js, index.html, package.json, tsconfig*.json, vite.config.ts, vitest.config.ts └─ CLAUDE.md, README.md, LICENSE (MIT) ``` ## Data model ```ts type Severity = 'légère' | 'modérée' | 'sévère'; type Vertebra = { region: 'C' | 'T' | 'L' | 'S' | 'Cd'; index: number }; type ObservationZone = { boneId: string; // matches data-anno-id from SVG detailSourceId?: string; // when this zone came from a detail pop-up SVG vertebrae?: Vertebra[]; // when boneId is a spine-zone }; type Observation = { id: string; zones: ObservationZone[]; pathologyIds: string[]; freeTextPathologies: string[]; severity?: Severity; comment: string; }; type Report = { version: 1; id: string; createdAt: string; // ISO date: string; // clinical date (ISO) practitioner: { name: string; cabinet?: string; contact?: string; siret?: string }; animal: { speciesId: string; name: string; breed?: string; age?: string }; owner: { name: string }; observations: Observation[]; conclusion: string; recommendations: string; nextAppointment?: | { kind: 'date'; date: string } | { kind: 'period'; text: string }; }; type PathologyCategory = | 'osseux' | 'articulaire' | 'musculaire' | 'tendino-ligamentaire' | 'fascial' | 'visceral' | 'cranio-sacre' | 'nerveux' | 'autre'; type PathologyRef = { type: 'manual' | 'journal' | 'database' | 'web'; citation: string; // human-readable url?: string; }; type Pathology = { id: string; // stable kebab-case labelFr: string; description: string; category: PathologyCategory; speciesIds: string[]; // [] = applicable to all species boneIds: string[]; // [] = applicable to all zones sources: PathologyRef[]; // 1+ }; ``` All JSON carries `version: 1`. Future migrations bump the version. ## SVG convention (source of truth) A clickable zone is any element carrying `data-anno-id`. Required data attributes: `data-anno-id`, `data-anno-name-fr`, `data-anno-name-en`, `data-anno-category`. Optional: `data-anno-opens-detail=""`. Categories: `articulation` · `charniere` · `spine-zone` · `os` · `os-overlay` · `head` · `cadran-crane`. Two rendering patterns are tolerated in the SVG: 1. **hitbox + visible twin** (articulation, charniere, os-overlay, head): two elements share the same `data-anno-id`. One has `class*="hitbox"`, transparent fill, `pointer-events: all`. The other has `class*="visible"`, colored fill, `pointer-events: none`. 2. **single element** (spine-zone, head zone): one polygon carries everything; `pointer-events: all` and `cursor: pointer` directly. Parser strategy (`src/anatomy/svgConvention.ts`): - Walk all elements with `data-anno-id`. - Group by `data-anno-id` → one logical `Bone`. - Bone fields: `id`, `fr`, `en`, `category`, `opensDetail?`, `hitboxEls[]`, `visibleEls[]`. - Validate: must have `data-anno-name-fr`, `data-anno-name-en`, `data-anno-category` (in the allowed enum). Throws structured `SvgConventionError` on missing attributes. Click handling: a single delegated listener on the root `` walks up from `event.target` to the nearest element with `data-anno-id`. If `data-anno-opens-detail` is present → open the detail modal mapped via the species manifest. If the bone's category is `spine-zone` → open the vertebra picker. Otherwise add the bone to the current observation. Colorization: when the current observation contains a bone, all elements matching that `data-anno-id` get a `data-state` attribute toggled by JS: `current` (solid accent), `linked` (faded dashed border, "in another observation"), `multi` (striped pattern, "in ≥2 observations"). > MVP scope cut: hover tooltip listing the owning observations is deferred. > Visual state classes alone communicate participation in v1. ## Detail-popup mechanism The mapping `detailId → SVG path` is held in the species manifest: ```ts // src/domain/species/equine/index.ts export const equine = { id: 'equine', mainSvg: '/species/equine/Horse.svg', details: { head: '/species/equine/Horse_head.svg' }, vertebralFormula: { C: 7, T: 18, L: 6, S: 5, Cd: 18 }, // approx Cd cap pathologies: () => import('./pathologies'), }; ``` When a zone with `data-anno-opens-detail="head"` is clicked, the canvas emits a `requestDetail({id: 'head'})` event handled by `DetailModal`, which loads `/species/equine/Horse_head.svg` and renders it inline. Clicks inside the modal add zones with `detailSourceId: 'head'` to the current observation. The "entry" zone (e.g. the head polygon itself) is never persisted in the report. ## Vertebra picker Triggered when a clicked bone has `data-anno-category="spine-zone"`. Modal with region tabs (Cervicales C1–C7, Thoraciques T1–T18, Lombaires L1–L6, Sacrales S1–S5, Caudales Cd1–Cd18). Each region renders chips in a grid; multi-select; ≥40 px touch targets; per-region "Tout cocher / décocher". Stored as `vertebrae: Vertebra[]` on the `ObservationZone` (replaces the global zone semantically: PDF prints precise vertebrae rather than the bloc). If a praticien clicks an individual vertebra (rendered under the same `bone-id` as the bloc), it is treated identically to clicking the spine-zone — opens the picker. Avoids duplicate UI paths. ## Multi-observation zone overlay A bone may belong to several observations. Visual states (`data-state` attribute on matching SVG elements, styled via `src/styles/index.css`): - `current` — bone is in the active observation. Solid accent fill. - `linked` — bone is in another observation (not current). Dashed border, faded accent fill. - `multi` — bone is in ≥2 observations. Same fill + heavier stroke to signal sharing. > MVP scope cut: per-observation HSL accent cycling (6 clinical-warm tones) > deferred to v1.1. v1 uses a single accent color across all states; PDF > renders per-observation pages, so colour ambiguity does not bleed into > the printed report. ## PDF format A4 portrait (595.28 × 841.89 pt). One pdf-lib document per export. Pages share a header drawer (praticien left block, animal+owner+date right) and a footer drawer (env-driven brand name, export date, page x/y). Per observation: one page with - the full main SVG rasterized at 2× scale with that observation's zones colored (canvg writes to canvas → PNG → `embedPng`); - if the observation includes detail-sourced zones (e.g. head): a second rasterization of the detail SVG with those zones colored, placed beside or below the main raster; - a structured block beneath the schematic: zones (with precise vertebrae formatted as "T12, T15"), pathologies (selected + free-text), severity, comment. > MVP scope cut: source citations under each cited pathology are deferred > to post-MVP. Pathology IDs/labels render without their `sources[]` block. Final page: conclusion, recommendations, next appointment. JSON attachment: the full `Report` object is serialized and attached via `pdfDoc.attach(bytes, 'osteo-report.json', { mimeType: 'application/json', description: 'Osteo Report state v1', creationDate, modificationDate, afRelationship: 'Data' })`. Bytes are pretty-printed JSON (UTF-8). MVP fonts: pdf-lib standard Helvetica + Helvetica-Bold (body) + Times-Roman (headings). Inter Sans + Fraunces TTF bundling deferred to v1.1 to avoid shipping ~600KB of font assets in the initial Docker image. ## PDF import `pdf-lib loadDocument()` → walk catalog `Names → EmbeddedFiles` tree → find an attachment whose filename starts with `osteo-report` and whose mime is `application/json` (or, fallback, parse-then-validate). Extract the stream, flate-decompress if needed (pako), parse JSON, validate with Zod. On success: hydrate the store and route to `/editor`. On failure: throw `ImportError` with the French message "Ce PDF n'a pas été généré par Osteo Report (pas de données détectées)." and show a toast. ## Configurable identity Env vars consumed at runtime: | Name | Default | Use | |---|---|---| | `PORT` | `8080` | nginx listen port. | | `APP_SITE_NAME` | `Osteo Report` | ``. | | `APP_BRAND_NAME` | `Osteo Report` | UI header, hero. | | `APP_FOOTER_NAME` | `Osteo Report` | PDF footer. | | `APP_TAGLINE` | `Bilans d'ostéopathie animalière` | Home tagline. | Mechanism: Docker entrypoint templates `index.html` to inject a `` tag using container env vars. `src/config/env.ts` reads `window.__APP_CONFIG__` first, falls back to `import.meta.env.VITE_APP_*` build-time values, then to defaults. `ConfigProvider` exposes the resolved config via React context. No identity string is hardcoded in any component. ## Routes - `/` — Home. Two CTAs ("Nouveau bilan", "Importer un PDF"). Quick-resume card if a sessionStorage draft exists. - `/new` — New report form. Species select (equine only for MVP), praticien fields (prefilled from `osteo:lastPractitioner`), animal (name + optional race/age), owner name, date (default today). - `/editor` — Editor. Split layout: anatomy canvas + observation panel. Bottom bar: export button. - `*` — NotFoundRoute. ## State persistence - Zustand store in memory. - sessionStorage mirror (`osteo:draft`) auto-restored on `/editor` if the user reloads accidentally; cleared after export. - localStorage (`osteo:lastPractitioner`) caches the praticien block to prefill next "Nouveau bilan". - No long-term storage. PDF is the only durable artifact. ## Test strategy - vitest + happy-dom. - TDD-first for: schema (Zod parse + reject malformed), store actions, id generator, anatomy convention parser (valid SVG → bones; bad SVG → structured error), pathology DB integrity (every entry validates + has ≥1 source), pdf attachment write+extract roundtrip on a fixture file. - UI smoke test: AnatomyCanvas mounts a fixture SVG and emits click for a known bone. - No e2e (no gstack plugin); manual QA in browser before commit. ## Docker / deploy Multi-stage Dockerfile: 1. **builder** — `node:20-alpine`. `corepack enable && pnpm i --frozen-lockfile && pnpm build`. 2. **runner** — `nginx:alpine`. Copy `dist/` to `/usr/share/nginx/html`, custom `nginx.conf` listening on `${PORT:-8080}`, `entrypoint.sh` writes `/usr/share/nginx/html/env.js` from `APP_*` env vars, then runs nginx. `docker-compose.yml` exposes `${PORT}:${PORT}` and passes `APP_*` env vars through `env_file`. The host nginx reverse-proxies any subdomain to that port. ## Open decisions resolved | Decision | Resolution | |---|---| | SVG injection | Fetch text → DOMParser → inline render (consistent + CSS-controllable + sandboxing irrelevant since assets are local). | | Vertebra picker UX | Region tabs + chip grid, multi-select, ≥40 px touch targets. | | Multi-obs zone overlay | current / linked / multi states; striped pattern + tooltip. | | Detail SVG trigger | `data-anno-opens-detail` → modal with inline detail SVG, clicks add to current obs. | | SVG → PDF | canvg → canvas @ 2× → PNG → `embedPng`. | | Pathology sources in PDF | Abbreviated citation list below each obs, no raw URLs. | | Brand env vars | Runtime `window.__APP_CONFIG__` + Vite-define fallback. | | MVP scope | Equine only. | | Drag-reorder obs | ↑/↓ buttons, no DnD. | | Practitioner default | localStorage cache. | | State persistence | sessionStorage mirror + PDF for long-term. | | Animation lib | motion 11. | | License | MIT. | ## Prerequisites / REMAINING - Real anatomical SVGs delivered by user at repo root: `Horse.svg` + `Horse_head.svg`. Moved into `public/species/equine/` by the scaffolder. - **Pathology DB authoring — deferred to post-MVP.** v1 ships with an empty `EQUINE_PATHOLOGIES = []` and a relaxed integrity test (length 0..100). Pathology picker shows the "aucune pathologie de référence" empty-state; praticien adds entries via free-text. Client osteo (or a Phase 2 multi-user authoring tool) will populate the curated DB once the long-term account architecture is decided. - **Source citations in PDF — deferred to v1.1.** Once the DB exists, re-enable the abbreviated-citation block on each observation page. - **Hover tooltip on canvas — deferred to v1.1.** Visual state classes alone in v1. - **Per-observation HSL accent cycling — deferred to v1.1.** Single accent in v1. - **Inter + Fraunces TTF bundling — deferred to v1.1.** PDF uses standard Helvetica + Times-Roman in v1. - **`docs/ADDING-A-SPECIES.md` — content to be authored** from the observed SVG convention + species manifest pattern (placeholder file exists today). - Final brand name, domain, identity strings. - Phase 2 (out of MVP): user accounts, server persistence, animal history, and curated pathology DB authoring tooling.