doc-syncer audit applied 10 AUTO patches and 1 HUMAN reword (#5) across the doc set. README.md: - Test count "7 tests pass on skeleton" / "88 tests across 23 files" → "155 tests" / "155 tests across 29 files". - Reword "Observation builder" bullet + add hierarchical findings tree + browser-detected locale bullets (HUMAN #5). - Status paragraph: pathology DB "intentionally empty" → full 26-zone v2.0 catalog (792 nodes, 612 leaves, 41 vet leaves). - Documentation section: add PATHOLOGIES-FORMAT.md link; tidy the DEPLOY.md mention (DEPLOY.md itself comes in the next commit). CLAUDE.md: - Architecture block: "embedFonts (Inter body + Fraunces heading)" → reality (Helvetica + TimesRoman / WinAnsi StandardFonts; TTF Inter/Fraunces planned). - PDF convention: "Fonts are TTF" → "Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi)" with the ASCII-surrogate caveat. - Folder map: add src/anatomy/labels.ts, include zoneMatch.ts in src/lib/{...}.ts. - i18n: locale default "fr" → "navigator-detected fr/en, or 'fr' if no match" to match commit9cf8a66. docs/PATHOLOGIES-FORMAT.md: - "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two places (after WinAnsi hotfix143fdc3). Picker ⚠ statement kept — browser renders U+26A0 natively. docs/ADDING-A-SPECIES.md: - data-anno-category: "Free-form" → enum of 7 valid values per ANATOMY-SVG-CONVENTION.md; parser throws SvgConventionError on unknown values. - Section 4 (findings catalog): cross-link to docs/PATHOLOGIES-FORMAT.md so authors find the v2.0 contract.
153 lines
5.9 KiB
Markdown
153 lines
5.9 KiB
Markdown
# 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`](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 (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
|
||
- **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
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```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 (155 tests)
|
||
pnpm build # tsc + vite build → dist/
|
||
```
|
||
|
||
---
|
||
|
||
## Build & deploy
|
||
|
||
```bash
|
||
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, 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
|
||
|
||
```
|
||
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/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
|
||
├─ docker/ entrypoint.sh + nginx.conf
|
||
└─ docs/ conventions + species guide + PDF spec
|
||
```
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
v1.0 MVP — implementation complete.
|
||
|
||
- `pnpm typecheck` ✅
|
||
- `pnpm lint` ✅
|
||
- `pnpm test:run` ✅ — 155 tests across 29 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).
|