Registry
--------
src/domain/species/registry.ts previously hard-coded the species list,
which meant adding a new animal forced an edit in two places. The
registry now uses Vite's `import.meta.glob('./*/index.ts', { eager: true })`
and registers every manifest that default-exports a SpeciesManifest.
Duplicate ids log a warn and the first wins. Existing named imports
keep working — equine/index.ts adds `export default equine` next to the
named export.
The species dropdown is also now sorted alphabetically by labelFr (FR
locale) instead of insertion order, so two species don't shuffle
position based on glob ordering.
Scaffold script
---------------
`pnpm scaffold:species` (scripts/scaffold-species.mjs) is an
interactive Node ESM prompt that asks for the id, FR/EN labels, asset
folder, main SVG filename, detail SVG mappings, and the vertebral
formula, then writes:
src/domain/species/<id>/index.ts (with `export default`)
src/domain/species/<id>/vertebrae.ts
src/domain/species/<id>/pathologies.ts (Zod-parses the JSON)
src/domain/species/<id>/pathologies.json (minimal valid skeleton)
public/species/<assetFolder>/ (directory placeholder)
The script refuses to overwrite existing files, so it's safe to rerun
after typos. SVG assets are not generated — drop them in the public
folder yourself.
Findings JSON updates
---------------------
No runtime hot-reload mechanism is needed in dev: `pathologies.ts`
imports `pathologies.json` and runs `SpeciesFindingsSchema.parse(data)`
at module load, so a JSON edit triggers Vite HMR + an immediate Zod
validation pass. In prod, rebuild and redeploy.
Docs
----
docs/ADDING-A-SPECIES.md rewritten around the new flow: quick start via
the scaffold script first, manual instructions second, and removed the
stale references to the flat `Pathology[]` model and the no-longer-
required registry edit step.
Co-Authored-By: Claude <noreply@anthropic.com>
Osteo Report
Web app for veterinary osteopaths to write session bilans on animal anatomy SVGs — click zones, build observations, export a self-contained PDF with the full report JSON embedded as a native PDF attachment. Re-importing that PDF restores the state for a follow-up.
Multi-species by design. MVP data set covers the horse (équin). Additional
species — dog, cat, goat, cow, pig, rabbit, donkey, sheep — drop in by adding
their SVG schematic + manifest + pathology file under src/domain/species/.
See docs/ADDING-A-SPECIES.md for the recipe.
Open to every praticien who wants to use it. No authentication, no backend, no central server in v1 — the PDF is the long-term record. Phase 2 will add optional praticien accounts + server-side persistence on the same data contract.
Features
- Anatomy canvas — inline SVG with clickable zones; hitbox+visible twin pattern; delegated click listener
- Observation builder — group zones into clinical observations with pathology selection, severity, and free-text notes
- Vertebra picker — region tabs (C/T/L/S/Cd) with multi-select chip grid for precise vertebral notation
- Detail popups — click a zone (e.g. head) to open a secondary SVG with finer-grained zones
- PDF export — A4 portrait with rasterized anatomy SVGs (canvg @ 2×), structured observations, and the full report JSON as a native PDF attachment
- PDF re-import — open a previously exported PDF to restore the session for a follow-up
- Configurable identity — site name, brand, footer, tagline all come from env vars; nothing hardcoded
- Practitioner cache — last-used practitioner block prefilled via localStorage
Stack
- Node.js 20
- React 19 + TypeScript 5 (strict)
- Vite 7 + @vitejs/plugin-react-swc
- Tailwind CSS v4 (CSS-first, no postcss config)
- Zustand 5 (state)
- Zod 3 (schema + runtime validation)
- pdf-lib 1.17 (PDF generation + native attachments)
- canvg 4 (SVG → canvas rasterization)
- motion 11 (animations)
- vitest 3 + happy-dom + @testing-library/react
Quick start (dev)
Single process, no Docker:
# Requires pnpm — install if needed:
curl -fsSL https://get.pnpm.io/install.sh | sh
source ~/.bashrc # or restart your shell
pnpm install
cp .env.example .env # edit APP_* vars if desired
pnpm dev # http://localhost:5173
Docker Compose (matches production topology):
cp .env.example .env # set APP_* identity vars
docker compose up --build
# app at http://localhost:8080
Verifying a change
pnpm typecheck # TypeScript strict, no emit
pnpm lint # ESLint 9 flat config, 0 warnings
pnpm test:run # vitest run (7 tests pass on skeleton)
pnpm build # tsc + vite build → dist/
Build & deploy
pnpm build # production build → dist/
docker build -t osteo-report . # multi-stage Docker image
docker compose up --build # run with env_file: .env
For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups) — see DEPLOY.md (to be written post-scaffold).
Documentation
- CLAUDE.md — project conventions, stack reference, architecture overview
- docs/ANATOMY-SVG-CONVENTION.md — SVG data-* contract (source of truth)
- docs/ADDING-A-SPECIES.md — guide for adding a second species post-MVP
- docs/PDF-FORMAT.md — PDF page layout and attachment contract
- .claude/tasks/TODO.md — implementation roadmap
Project layout
osteo/
├─ public/species/equine/ anatomy SVGs (Horse.svg, Horse_head.svg)
├─ src/app/ routes + ConfigProvider
├─ src/config/ runtime env config resolution
├─ src/domain/ Zod schemas + species registry + equine data
├─ src/state/ Zustand store + localStorage cache
├─ src/anatomy/ SVG parser + loader
├─ src/components/ UI primitives, canvas, observation, report
├─ src/pdf/ export/import/attachment/fonts + renderers
├─ src/lib/ id, dates, assert utilities
├─ src/styles/ Tailwind v4 CSS + design tokens
├─ tests/unit/ vitest tests
├─ docker/ entrypoint.sh + nginx.conf
└─ docs/ conventions + species guide + PDF spec
Status
v1.0 MVP — implementation complete.
pnpm typecheck✅pnpm lint✅pnpm test:run✅ — 88 tests across 23 filespnpm build✅ — 979 kB JS (349 kB gzip), 20 kB CSS
The first species data set ships with the real Horse.svg + Horse_head.svg
anatomy sources at public/species/equine/. Adding dog, cat, goat, cow,
pig, rabbit, donkey, sheep is the same procedure: convention-compliant SVG +
manifest + pathology file. See docs/ADDING-A-SPECIES.md.
The pathology reference DB is intentionally empty in v1; the praticien adds
entries via the free-text input. Source-cited DB authoring is deferred to
v1.1 once the multi-praticien account architecture is decided (see
docs/superpowers/specs/2026-05-18-osteo-report-mvp-design.md
§Prerequisites/REMAINING).
Manual QA checklist: .claude/audits/MVP-QA.md — walk it through pnpm dev
before delivery.
License: MIT.