7.6 KiB
Faunosteo
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. The MVP ships the horse sheet: a canonical anatomical
sheet document (drawing + annotations + findings catalog, packages/domain)
generated and curated under supabase/seed/anatomical-sheets/equine/. Another
species is another sheet document, no code change.
See docs/development/ANATOMICAL_SHEET_MODEL.md §6 for how a sheet is produced.
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 drawing with markers rendered from the sheet document (hitbox + visible twin, delegated click listener)
- Observation builder — group zones into clinical observations with severity and free-text notes
- Hierarchical findings tree — per-zone picker with breadcrumb drill-down through the expert-authored catalog (26 zones for the horse), vet-referral badges on sensitive leaves, scope-disclaimer modal once per session
- Vertebra picker — region tabs (C/T/L/S/Cd) with multi-select chip grid for precise vertebral notation
- Detail views — click the head trigger to open the head view (a crop of the same drawing, or a view's own asset)
- PDF export — A4 portrait with rasterized views, structured observations, and the full Report v3 JSON as a native PDF attachment; older v2 PDFs import through a generated migration map
- PDF re-import — open a previously exported PDF to restore the session for a follow-up
- Bilingual UI — full FR/EN interface with a one-click language switcher; default locale auto-detected from the browser, then persisted
- Configurable identity — site name, brand, footer, tagline all come from env vars; nothing hardcoded
- Practitioner cache — last-used practitioner block prefilled via localStorage
- Laterality — left/right side selection on bilateral zones, reflected in badges and the PDF
- Footer branding — global footer (copyright, "Powered by ZenQuality", partner logo), on site + PDF
Stack
- Node.js 24 LTS + pnpm 10.13 (corepack)
- 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)
- motion 11 (animations)
- vitest 3 + happy-dom + @testing-library/react
- Supabase (PostgreSQL 17, Auth, RLS) via the pinned CLI;
@supabase/supabase-js2; PGlite for Dockerless SQL tests
Quick start (dev)
Single process, no Docker:
# Node 24 (see .nvmrc) + pnpm 10.13.1 via corepack, no global install:
corepack enable
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 (domain, anatomy, supabase/PGlite, app)
pnpm build # tsc + vite build → apps/app/dist/
pnpm report:compare <pdf|dir>... # archive PDF vs its v3 reading, unresolved items flagged
Build & deploy
pnpm build # production build → apps/app/dist/
docker build -t faunosteo . # multi-stage Docker image
docker compose up --build # run with env_file: .env
For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups, hardening) — see DEPLOY.md.
Documentation
- CLAUDE.md — project conventions, stack reference, architecture overview
- docs/ANNOTATION-RENDERING.md — annotation layer contract (markers drawn from the sheet document)
- docs/development/ANATOMICAL_SHEET_MODEL.md — canonical anatomical sheet document, curation pipeline, report migration map
- docs/development/STEP5_MIGRATION_ANALYSIS.md — how the application moved onto the canonical sheet (Report v3)
- docs/PDF-FORMAT.md — PDF page layout and attachment contract
- docs/development/SUPABASE.md — local Supabase stack, migrations, RLS tests, generated types
- DEPLOY.md — production VPS deploy guide (Docker + nginx + TLS + hardening)
- CHANGELOG.md — versioned release notes
- .claude/tasks/TODO.md — implementation roadmap
Project layout
faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md)
├─ apps/app/ the private application (@faunosteo/app):
├─ vite/sheet-bundle.ts Vite plugin bundling the reference sheet (SHEET_BUNDLE=draft|none)
├─ src/app/ routes + ConfigProvider
├─ src/config/ runtime env config resolution
├─ src/sheets/ SheetProvider (bundled implementation) + useSheet hook
├─ src/services/ sheet index (lookups by id) + zone interaction service (pure)
├─ src/i18n/ translation dicts (fr/en) + useT() hook
├─ src/state/ Zustand store (Report v3) + persistence adapter + locale store
├─ src/anatomy/ drawing: sanitised asset + annotation layer → inline SVG per view
├─ 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 on the bundled sheet (+ frozen v2 fixtures)
├─ packages/domain/ @faunosteo/domain: canonical sheet document + report document (v3, v2 migration)
├─ packages/anatomy/ @faunosteo/anatomy: legacy importer, curation pipeline, annotation-layer renderer
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL test harness
├─ supabase/ CLI config, SQL migrations, local seed (incl. the equine sheet), pgTAP tests
├─ docker/ entrypoint.sh + nginx.conf
├─ docs/ conventions, sheet model, PDF spec, development plan
└─ index.html SPA entry point
Status
v0.1.0 MVP — implementation complete.
pnpm typecheck✅pnpm lint✅pnpm test:run✅ — 367 tests across the workspace (domain, anatomy, supabase, app)pnpm build✅
The first species ships as the equine anatomical sheet: the historical
Horse.svg, Horse_head.svg and findings catalog (26 zones, 792 nodes)
imported, then audited and curated (supabase/seed/anatomical-sheets/equine/,
45 traced changes, 48 references). The application bundles that curated
draft in development (SHEET_BUNDLE=draft); it is not medically validated and
a production build carries no sheet unless asked. Another species is another
sheet document produced the same way.
Manual QA checklist: .claude/audits/MVP-QA.md — walk it through pnpm dev
before delivery.
License: MIT.