Files
faunosteo/docs/history/superpowers/specs/2026-05-18-osteo-report-mvp-design.md
T
bchanot 02052f3622 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.
2026-10-08 21:51:13 +02:00

17 KiB
Raw Blame History

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

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:

// 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.