User updated the clickable-zone convention in the source SVGs:
data-bone-id → data-anno-id
data-bone-fr → data-anno-name-fr
data-bone-en → data-anno-name-en
data-category → data-anno-category
data-opens-detail → data-anno-opens-detail
Bulk-renamed across:
- public/species/equine/Horse.svg + Horse_head.svg (86 anno-attrs each)
- src/anatomy/svgConvention.ts (parser + getBoneIdFromEvent)
- src/anatomy/types.ts (doc strings)
- src/components/canvas/AnatomyCanvas.tsx (querySelector + delegated click)
- src/styles/index.css (`[data-bone-id]` selectors → `[data-anno-id]`)
- src/domain/species/types.ts + schema/observation.ts (doc strings)
- docs/{ANATOMY-SVG-CONVENTION,ADDING-A-SPECIES,superpowers/specs,plans}.md
- CLAUDE.md + .claude/{memory/learnings,tasks/TODO}.md
- tests/unit/{anatomy.svgConvention,anatomy.svgLoader,components.AnatomyCanvas}.test.tsx
Internal TS type names and field names (Bone, boneId, parseSvgBones,
getBoneIdFromEvent) are kept intentionally — they're the application's
logical shape and the persisted JSON contract. ObservationZone.boneId is
the identifier seen in already-exported PDFs; renaming it would break
re-import of those PDFs. Only the SVG-side attribute names change.
90/90 tests pass, lint clean, build clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
379 lines
17 KiB
Markdown
379 lines
17 KiB
Markdown
# 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/<id>/`. 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="<id>"`.
|
||
|
||
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 `<svg>` 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` | `<title>`. |
|
||
| `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
|
||
`<script>window.__APP_CONFIG__ = {...}</script>` 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.
|