docs(docs): restore 2026-05 design specs and plans under docs/history

Purged from docs/superpowers by the gitflow finish of step 1 (BDR-065);
that path is purged at every finish, so the records live under
docs/history/superpowers/ instead. References updated.
This commit is contained in:
bchanot committed 2026-10-08 21:51:13 +02:00
1 parent 8673475293
commit 02052f3622
12 files changed
+8581 -3

No files matched your search

@@ -0,0 +1,378 @@
# 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.