A draft the core refuses as lone_surrogate is unreadable content: it
goes to osteo:quarantine:draft verbatim with the existing notice. An
import is refused as ImportError('lone_surrogate') with the owner's
wording (home.import.error_lone_surrogate, FR/EN), the file untouched.
The publish gate reads the kind as invalid_shape. Tests on the real
core: quarantine keeps the exact text, an editor action leaves the
report as it was, normal text with pairs and literal backslashes reads
unchanged.
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
Development server on the private network (the DEV origin is the machine's
LAN address, scripts/dev-env.sh): pnpm db:start, then pnpm dev and open
http://<lan-address>:5173 from any device of the network; Mailpit for the
sign-up mails on :54324 (docs/development/ENVIRONMENTS.md).
Rust (core, browser module, worker): a user-level rustup installs the
pinned toolchain from rust-toolchain.toml on first use; see
docs/development/RUST.md §1 for the three cargo install / rustup target add lines and the Docker alternative. The files worker (profile
photos, Step 8) runs as a container beside the local Supabase stack:
pnpm worker:image, then pnpm e2e:avatar for the real-stack end-to-end
run, or docker compose --profile worker up worker with a .env.worker
(docs/development/STORAGE.md).
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
pnpm rust:check # native: fmt, clippy -D warnings, cargo test, ts-rs export, cargo deny
pnpm wasm:build # native: browser module → packages/core-wasm/pkg (the core-wasm proofs run on it)
pnpm check:all # everything a branch must pass before a merge, in one command (needs Docker for the image stages)
No CI/CD runs on the forge yet: the workflow files under .gitea/workflows/
are prepared for a future runner and call these same scripts.
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 pages, report archive envelope (snapshot, branding, labels), reading and limits
- docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md — why and how the PDF became an autonomous archive (Step 6)
- docs/development/PDF_IMPORT_HARDENING.md — PDF import against decompression bombs: what lands now, what is required before external users
- 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/ app side of the PDF: snapshot + branding + browser rasterizer → @faunosteo/pdf engine
├─ 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 + view composer
├─ packages/pdf/ @faunosteo/pdf: browser-free PDF engine (explicit inputs, archive envelope v1, layered reader)
├─ 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.