The owner tests from other devices of the private network: every test surface is addressed by the machine's LAN address, never 127.0.0.1 or localhost, never hard-coded. scripts/dev-env.sh decides the host once (hostname -I, FAUNOSTEO_DEV_HOST override, production hosts refused); scripts/supabase.sh exports it for every CLI call (pnpm db:*, pnpm supabase) because config.toml now reads api.external_url (mail links), auth.site_url and studio.api_url with env(); scripts/dev.sh = pnpm dev on that origin, pnpm dev:offline keeps the local tool alone; dev-lan.sh removed. Verified: GoTrue API_EXTERNAL_URL and Studio SUPABASE_PUBLIC_URL on the LAN address, a signup mail linking to http://<lan>:54321/auth/v1/verify, the four published ports answering from a separate Docker network, and the 10-step procedure in headless Chromium at the LAN origin with every request URL audited (no 127.0.0.1 / localhost).
187 lines
9.4 KiB
Markdown
187 lines
9.4 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. 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-js` 2; PGlite for Dockerless SQL tests
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
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):
|
|
|
|
```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 (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
|
|
|
|
```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/ANNOTATION-RENDERING.md](docs/ANNOTATION-RENDERING.md) — annotation layer contract (markers drawn from the sheet document)
|
|
- [docs/development/ANATOMICAL_SHEET_MODEL.md](docs/development/ANATOMICAL_SHEET_MODEL.md) — canonical anatomical sheet document, curation pipeline, report migration map
|
|
- [docs/development/STEP5_MIGRATION_ANALYSIS.md](docs/development/STEP5_MIGRATION_ANALYSIS.md) — how the application moved onto the canonical sheet (Report v3)
|
|
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF pages, report archive envelope (snapshot, branding, labels), reading and limits
|
|
- [docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md](docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md) — why and how the PDF became an autonomous archive (Step 6)
|
|
- [docs/development/PDF_IMPORT_HARDENING.md](docs/development/PDF_IMPORT_HARDENING.md) — PDF import against decompression bombs: what lands now, what is required before external users
|
|
- [docs/development/SUPABASE.md](docs/development/SUPABASE.md) — local Supabase stack, migrations, RLS tests, generated types
|
|
- [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):
|
|
├─ 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](LICENSE).
|