Files
faunosteo/README.md
T
bchanot 8673475293 chore(workspace): move the app to apps/app under a pnpm workspace (step 2)
144 files moved with git mv (pure renames). Root package.json delegates
dev/typecheck/test:run/lint/build to the packages; Node 24 LTS and
pnpm 10.13.1 pinned (.nvmrc, .node-version, engines, packageManager,
root devDependency, engine-strict). Dockerfile builds @faunosteo/app on
node:24-alpine and copies apps/app/dist; nginx and runtime config
unchanged. CI workflow for Gitea Actions. packages/ reserved (README only).
Docs synced: WORKSPACE.md, CLAUDE.md, README, DEPLOY, CHANGELOG, plan.
271/271 tests, typecheck, lint, build green from the root.
2026-10-08 21:51:13 +02:00

160 lines
6.8 KiB
Markdown

# 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. 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`](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 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 popups** — click a zone (e.g. head) to open a secondary SVG with finer-grained zones
- **PDF export** — A4 portrait with rasterized anatomy SVGs (native browser `Image`/`canvas` pipeline), 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
- **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
- **Pathology editor** — standalone `pathology-editor.html` tool (no build step) for visually editing the species findings JSON via SVG zone selection; exports a downloadable JSON file
- **Laterality** — left/right side selection on bilateral zones, reflected in badges and the PDF
- **SVG anatomy editor** — in-app `/svg-editor` tool to annotate anatomy SVGs
- **Welcome screen + editors page** — tabbed entry with a project SVG picker and an `/editors` listing
- **Footer branding** — global footer (copyright, "Powered by ZenQuality", partner logo), on site + PDF
---
## 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)
- motion 11 (animations)
- vitest 3 + happy-dom + @testing-library/react
---
## Quick start (dev)
Single process, no Docker:
```bash
# 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):
```bash
cp .env.example .env # set APP_* identity vars
docker compose up --build
# app at http://localhost:8080
```
---
## Verifying a change
```bash
pnpm typecheck # TypeScript strict, no emit
pnpm lint # ESLint 9 flat config, 0 warnings
pnpm test:run # vitest run (271 tests)
pnpm build # tsc + vite build → apps/app/dist/
```
---
## Build & deploy
```bash
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](DEPLOY.md).
---
## Documentation
- [CLAUDE.md](CLAUDE.md) — project conventions, stack reference, architecture overview
- [docs/ANATOMY-SVG-CONVENTION.md](docs/ANATOMY-SVG-CONVENTION.md) — SVG data-* contract (source of truth)
- [docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) — guide for adding a second species post-MVP
- [docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md) — findings catalog format + authoring guide
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract
- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening)
- [CHANGELOG.md](CHANGELOG.md) — versioned release notes
- [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — implementation roadmap
---
## Project layout
```
faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md)
├─ apps/app/ the private application (@faunosteo/app):
├─ 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/i18n/ translation dicts (fr/en) + useT() hook
├─ src/state/ Zustand store + locale 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 (apps/app/tests, incl. characterisation suite)
├─ packages/ shared packages, none yet
├─ docker/ entrypoint.sh + nginx.conf
├─ docs/ conventions + species guide + PDF spec
├─ index.html SPA entry point
└─ public/pathology-editor.html standalone pathology JSON editor (served as static file)
```
---
## Status
v0.1.0 MVP — implementation complete.
- `pnpm typecheck` ✅
- `pnpm lint` ✅
- `pnpm test:run` ✅ — 271 tests across 39 files
- `pnpm build` ✅
The first species data set ships with the real `Horse.svg` + `Horse_head.svg`
anatomy sources at `public/species/equine/` and a full v2.0 findings catalog
(26 zones, 792 nodes, 612 leaves, 41 vet-referral leaves) authored by the
domain expert. Adding **dog, cat, goat, cow, pig, rabbit, donkey, sheep** is
the same procedure: convention-compliant SVG + manifest + findings JSON. See
[docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) and
[docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md).
Manual QA checklist: `.claude/audits/MVP-QA.md` — walk it through `pnpm dev`
before delivery.
License: [MIT](LICENSE).