# Faunosteo — CLAUDE.md # Generated by scaffolder 2026-05-18. Single source of truth for Claude in this repo. # Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them. --- ## Project overview **Faunosteo** is the official, final product name (the SaaS, the application, the public site and its services); official domain **https://faunosteo.com** (production, separate VPS, the site present there is preserved until an explicit migration decision). Never propose another brand name; keep the logo, palette and validated mockups. Environments DEV / STAGING (`staging.faunosteo.com`, planned, not created) / PROD are isolated (`docs/development/ENVIRONMENTS.md`). Single-praticien French web app for veterinary osteopathy bilans on animal anatomy SVGs. Practitioner clicks anatomical zones, builds observations with pathologies/severity, writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native attachment so importing it restores the session for a follow-up. SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase (PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and audit log exist; Step 4 added the canonical anatomical sheet model (since R2 in `crates/core/src/domain/sheet`; the TypeScript `packages/domain` left at R5.7), tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the application onto that model: the editor renders the bundled reference sheet (the curated equine DRAFT, `SHEET_BUNDLE=draft`), writes Report v3 and imports v2 PDFs through a generated migration map. Step 6 made the PDF an autonomous archive: the PDF engine (TypeScript `packages/pdf` until R4, the Rust core `crates/core/src/pdf` since) renders from explicit inputs (report, sheet snapshot, branding, labels, rasterizer) with no network and no DOM, and the attachment is an envelope v1 carrying the report, a lean sheet snapshot, the branding and the labels used, so an old bilan is reproduced identically after any catalog, wording or logo change (`docs/PDF-FORMAT.md`). Step 7 added identity: email/password sign-up with confirmation, password recovery, OAuth buttons driven by config, the guarded `/app` shell (dashboard, Mon compte with personal / professional / preferences / security sections) on Supabase Auth + `profiles` + `profile_roles`, language synced with `profiles.locale` (`docs/development/IDENTITY.md`). The local tool routes stay unauthenticated. Step 8 (= Rust R1) added the files foundation: the `assets` table as the authority over user files, seven private buckets (only `avatars` open, through policies evaluated on `assets`), a quarantine upload path, the Rust worker `crates/worker` (keyed job loop + keyless sandboxed decode child) producing 512 × 512 WebP avatars, a deferred purge queue, and the profile photo in Mon compte, the sidebar, the drawer and the top bar (`docs/development/STORAGE.md`). Rust R2 moved the application's domain rules into `crates/core` (sheet, report and archive contracts, integrity rules, sheet index, migration, rebase, snapshot, layered archive reading, editor reducers, findings and vertebra rules, report operations), reached through the wasm facade and `packages/core-wasm`, loaded lazily by the sheet pages only (`docs/development/RUST.md` §8). R5 moved the anatomical pipeline (legacy importer, curation, migration map, review files, seed SQL, upload tool) into the core (feature `curation`); R5.6 switched the sheet fingerprint to `sha256-rfc8785-validated-v1`; R5.7 deleted `packages/anatomy` and `packages/domain` (`RUST.md` §11.23, test ledger `crates/core/tests/curation/LEDGER.tsv`). MVP species: equine only for anatomical sheets (V1-1.4 records ten species of animals; no sheet beyond the equine draft). Open-source MIT. Product roadmap (owner, 2026-10-25): P0 docs, then V1-1 clients and animals, V1-2 sheets from Supabase, V1-3 cloud bilans, V1-4 stored PDF and sharing, V1-5 mobile and accessibility pass (`docs/development/IMPLEMENTATION_PLAN.md` §0; V1-1 contract `docs/development/V1-1_OWNERS_ANIMALS.md`: business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validated, BDR-074; on `feature/v1-1-clients-animals` V1-1.1 to V1-1.5 (validated) and V1-1.6 are built: migrations `20261025100000_workspaces.sql`, `20261025110000_clients.sql` and `20261026100000_animals_relations.sql` (contract §8.3), tested on PGlite and the isolated stack `pnpm db:sandbox`, not applied to Supabase DEV; V1-1.3 the native modal dialog (D13) and the Playwright + axe suites (D14, `docs/development/BROWSER_TESTS.md`); V1-1.5 the client screens (`/app/clients`, contract §11.7) and V1-1.6 the animal screens and the relations (`/app/animals`, contract §11.8; D11: drawer only, no tab bar) on the isolated stack). --- ## Stack | Concern | Choice | Version | |---|---|---| | Runtime | Node.js | 24 LTS (`.nvmrc`, `engines` >=22.12 <25) | | Package manager | pnpm | 10.13.1 (`packageManager`, root devDependency) | | Build | Vite + @vitejs/plugin-react-swc | 7.x | | UI | React | 19 | | Language | TypeScript strict | 5.x | | Styling | Tailwind CSS v4 CSS-first (no postcss config) | 4.x | | State | Zustand | 5 | | Validation | Zod | 3 | | PDF | the Rust core's reader and writer (`crates/core/src/pdf`, R4; no PDF library) | — | | SVG raster | native Image/canvas (no dependency) | — | | Animation | motion | 11 | | Tests | vitest + happy-dom + @testing-library/react | 3.x | | Browser tests | @playwright/test (Chromium 1248) + @axe-core/playwright, pinned dev deps of apps/app (`docs/development/BROWSER_TESTS.md`) | 1.64.1 / 4.14.0 | | Backend | Supabase (PostgreSQL 17, GoTrue, PostgREST) — CLI pinned as root devDependency | CLI 2.120 | | DB client | @supabase/supabase-js (packages/supabase) | 2.x | | SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 | | Deploy | Docker multi-stage → nginx:alpine | — | | Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; native user-level rustup on the Ubuntu development machine (`pnpm rust:check`, `pnpm wasm:build`, plain `cargo`), the builder image `docker/rust-builder.Dockerfile` as the reproducible alternative (`:docker` scripts), never on the VPS | 1.99.0 | | WASM glue | wasm-bindgen crate = CLI version (locked in `scripts/wasm-build.sh`), `ts-rs` types committed under `packages/core-wasm/types` | 0.2.129 / 12 | | Worker image | `crates/worker/Dockerfile`: `rust:1.99.0-alpine3.24` (musl, libwebp via `cc`) → `distroless/static:nonroot`; sandbox tests + seccomp derivation in the `test` stage | — | --- ## Build commands pnpm workspace: `apps/app` = the private application, `packages/core-wasm` = the Rust core in the browser (runtime, generated types, frozen N-1 reader), `packages/supabase` = Supabase access layer (see `docs/development/WORKSPACE.md`). Every command below runs from the repository root and delegates to the packages. ```bash # Development (DEV origin = this machine's LAN address, scripts/dev-env.sh; tests run from other devices) pnpm dev # Vite on http://:5173 wired to the local stack (needs pnpm db:start) pnpm dev:offline # the local tool without backend pnpm dev:gateway # Mailpit behind basic auth on FAUNOSTEO_DEV_HOST:54325; dev:gateway:stop pnpm dev:net-check # allowed / refused probes from a distinct Docker network # Production build (typecheck + vite build) pnpm build # Type-check only (no emit) pnpm typecheck # Preview production build pnpm preview # Tests (watch) pnpm test # Tests (CI / single run) pnpm test:run # Lint (0 warnings allowed) pnpm lint # Format pnpm format # Supabase local stack (Docker) — docs/development/SUPABASE.md; every CLI call goes through # scripts/supabase.sh (exports the DEV origin that config.toml reads with env()); `pnpm supabase ` pnpm db:start # start stack, apply migrations + seed; FAUNOSTEO_DEV_HOST= to pick another address pnpm db:reset # replay from zero pnpm db:test # pgTAP on the real stack pnpm db:types # regenerate packages/supabase/src/database.types.ts pnpm db:types:check # CI diff pnpm db:sandbox up fresh|up upgrade []|test-db|types [--check]|test|e2e-shell|avatar-e2e|down # throwaway stack (SUPABASE.md §5.1): migrations tested without touching DEV # Reference sheet in the app: the dev server bundles the curated draft; a build does not pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments) pnpm preview:draft # same, then serves it pnpm import:equine --check | --out # since R5.6 the official seed writer: the Rust pipeline (same as `pnpm r5:import-equine`), fingerprint `sha256-rfc8785-validated-v1`; the TypeScript generator left at R5.7 (replayed from a historical revision only, RUST.md §11.23) pnpm r5:import-equine --check | --out # the Rust pipeline (R5.2 importer, R5.3 draft, R5.4 review files): compare the 18 generated files with the committed folders (bytes; app drawings under the declared R3 rule), or write /{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles) pnpm assets:upload [--check] # R5.5: uploads the sheet drawings of a generated seed folder to the LOCAL stack's private bucket (Rust `upload-sheet-assets`, feature `upload`; SUPABASE_URL local with a port, SUPABASE_SERVICE_ROLE_KEY typed, never printed; no overwrite, confirm after verify; run by hand, scripts/upload-sheet-assets.sh) pnpm e2e:sheet-assets # scripts/sheet-assets-e2e.sh: sandbox only, refuses before any request unless the sandbox gateway URL and keys naming the sandbox issuer are set (its runner `pnpm db:sandbox sheet-assets-e2e` arrives with V1-2); never DEV pnpm report:compare ... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md); the core's `report-compare` binary since R4.7 (scripts/report-compare.sh, first run compiles) # Rust (docs/development/RUST.md) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first pnpm rust:check # scripts/rust-check.sh: fmt --check, clippy -D warnings, cargo test (core, wasm, worker unit), ts-rs export, cargo deny pnpm wasm:build # scripts/wasm-build.sh: crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run pnpm check:all # scripts/check-all.sh: the whole pre-merge gate (rust:check, types drift, wasm:build, check, app image, worker:test, worker:image) pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0), the reproducible alternative pnpm rust:check:docker # the same rust-check.sh inside the builder image pnpm wasm:build:docker # the same wasm-build.sh inside the builder image pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, sandbox tests + seccomp derivation on the musl binary pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static, `run --check`) pnpm e2e:avatar # = pnpm db:sandbox avatar-e2e: the worker container and packages/supabase/tests/e2e on the throwaway stack only (the suite refuses any other target; no DEV variant since 2026-11-02) ``` ## Test commands ```bash pnpm test:run # vitest run — all tests, single pass, CI-safe pnpm test # vitest watch — dev loop pnpm e2e:ui # Playwright Chromium, no backend: Dialog test page + local tool dialogs, desktop + 375 px, axe (in check:all when the pinned Chromium is installed) pnpm e2e:shell # Playwright Chromium against `pnpm db:sandbox` (must be up): sign-in, dashboard, photo confirmation, phone drawer, client, animal and relation journeys; never DEV (`pnpm db:sandbox e2e-shell [--grep]` for one file) ``` Browser suites (`apps/app/e2e`, `docs/development/BROWSER_TESTS.md`): Chromium only until V1-5, `pnpm --filter @faunosteo/app exec playwright install chromium` once (no sudo, never `--with-deps`); loopback dev servers of their own (5191, 5192, `--strictPort`, never reused); every request outside the suite's allowlist is aborted and fails the test; the shell suite keeps no trace (session tokens). Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in `apps/app/tests/fixtures/`. The 612 legacy catalog leaves run through the v2 → v3 migration in the core (`crates/core/tests/curation_leaves.rs`, against the draft document) and the app (sheet index + PDF roundtrip). Setup: `apps/app/tests/setup.ts` imports @testing-library/jest-dom. Suites run on the bundled reference sheet (`tests/helpers/sheet.ts`); frozen v2 fixtures under `tests/fixtures/`. SQL: `supabase/tests/*.sql` (pgTAP) run by `packages/supabase/tests/db/pgtap.test.ts` on PGlite (part of `pnpm test:run`) and by `pnpm db:test` on the real stack. --- ## Lint / format commands ```bash pnpm lint # ESLint 9 flat config — max-warnings 0 pnpm format # Prettier write ``` --- ## Folder structure ``` faunosteo/ ├─ apps/app/ ← @faunosteo/app (everything below until packages/) ├─ public/ ← favicons, env.js, site header logo only (PDF logos live in src/assets/brand; no anatomy asset) ├─ vite/sheet-bundle.ts ← Vite plugin: `virtual:faunosteo-sheet` (SHEET_BUNDLE=draft|none) ├─ src/ │ ├─ assets/brand/ ← the four PDF branding logos and the footer's ZenQuality logo, bundled by Vite (?inline / ?raw / ?url), never fetched (production CSP img-src 'self') │ ├─ app/ │ │ ├─ App.tsx ← root router │ │ ├─ useUnsavedGuard.ts ← beforeunload while the report is unsaved, called once in App │ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx │ │ ├─ routes/auth/{Login,Signup,ForgotPassword,ResetPassword,AuthCallback}Route.tsx │ │ ├─ routes/app/{Dashboard,Account}Route.tsx ← behind RequireAuth, inside AppLayout │ │ ├─ routes/app/clients/{ClientsList,ClientCreate,ClientDetail,ClientEdit}Route.tsx ← V1-1.5, behind RequireWorkspace │ │ ├─ routes/app/animals/{AnimalsList,AnimalCreate,AnimalDetail,AnimalEdit}Route.tsx ← V1-1.6, same RequireWorkspace; the first client arrives in the navigation state, never the URL │ │ ├─ guards/{RequireAuth,RedirectIfSignedIn,SessionLoading,RequireWorkspace}.tsx ← RequireWorkspace: personal workspace ready, remount per workspace, species labels (SpeciesProvider) │ │ ├─ useLeaveGuard.ts + usePageHeading.ts ← unsaved changes (beforeunload + in-app links via AppLayout); heading focus on page open │ │ └─ providers/{ConfigProvider,AuthProvider}.tsx ← AppConfig context; session + locale sync start │ ├─ auth/{validation,redirects,useAuthFailureMessage}.ts ← Zod schemas (i18n keys), safe next path, failure phrasing │ ├─ account/{validation,useProfileForm}.ts ← account section schemas + one-save form hook │ ├─ config/env.ts ← runtime config resolution │ ├─ sheets/{provider,useSheet}.ts ← raw bundled payload; useSheet loads it into the core (ready / none / core_unavailable / invalid_sheet + retry), useSheetAvailability without the core │ ├─ core/{runtime,sheetOps,reportOps}.ts ← the page's CoreRuntime (Vite asset URLs, lazy), typed sheet-bound and free core operations │ ├─ services/ │ │ ├─ sheetIndex.ts ← SheetIndex class: reads the core's SheetIndexData (ids, never labels) + `ops` │ │ └─ localeSync.ts ← profiles.locale ↔ localeStore (account wins on sign-in) │ ├─ i18n/ │ │ ├─ types.ts ← Locale type + Dict type │ │ ├─ fr.ts + en.ts ← translation dicts (flat key → string) │ │ ├─ index.ts ← getDict(locale) │ │ └─ useT.ts ← useT() hook (reads localeStore) │ ├─ state/ │ │ ├─ authStore.ts ← session, user, profile, roles, recovery flag, personal workspace state (onAuthStateChange; reset on account change) │ │ ├─ leaveGuardStore.ts ← armed while a page holds unsaved changes │ │ ├─ reportStore.ts ← Zustand store (Report v3, core-built reports, actions answer { ok }) + persistence.ts (raw texts, quarantine keys) │ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage) │ │ └─ practitionerCache.ts ← localStorage prefill │ ├─ clients/{validation,countries,useClientForm,useClientList,useClientRecord}.ts ← client form schema on field-limits (D-R7), ISO list, page-local hooks │ ├─ animals/{validation,age,species,useAnimalForm,useAnimalList,useAnimalRecord}.ts(x) ← animal form schema (D-R7, U3 birth, no default sex or role), display age, species context │ ├─ relations/{groups,choices,useAnimalRelations}.ts ← an animal's relations (current / former), stable picker searches │ ├─ anatomy/drawing.ts ← the core's composed view (`view.canvas`) → DOMParser → importNode (R3; no sanitiser here) │ ├─ components/ │ │ ├─ ui/{Button,ButtonLink,Card,Dialog,ModalDialog,Input,Label,Select,Textarea,Badge,Chip,ChoiceRadios,Icon,FormField,Notice}.tsx ← ModalDialog: native showModal (D13), Dialog and MobileDrawer on it │ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx │ │ ├─ observation/{ObservationList,ObservationCard,ObservationPickers,FindingsTreePicker, │ │ │ VertebraPicker,SeveritySelector,LateralityPicker, │ │ │ FreeTextFindingInput}.tsx │ │ ├─ report/{ReportHeader,PractitionerForm,AnimalForm,EditInfosDialog,DisclaimerDialog, │ │ │ ConclusionPanel,NextAppointmentPicker,CoreUnavailable,HeldSessionPanel,ReplaceSessionDialog}.tsx │ │ ├─ brand/{Brand,AppHeader,Footer,LanguageSwitcher,HomeSpaceLink}.tsx │ │ ├─ auth/{AuthLayout,OAuthButtons,PasswordField,UnavailableNotice,AuthLink}.tsx │ │ ├─ clients/{ClientForm,ClientAnimals,ArchiveClientDialog,ClientNotFound}.tsx │ │ ├─ animals/{AnimalForm,ArchiveAnimalDialog,AnimalNotFound}.tsx │ │ ├─ relations/{AnimalRelations,RelationPanel,RelationActionDialog,RelationDialogs,RecordPicker,Pickers}.tsx ← in-page link panel, end / dates / void confirmations │ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx │ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx │ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob │ ├─ pdf/ ← the app side of the PDF (export on the core's session since R4.6; the import runs in the worker, `core/worker`) │ │ ├─ export.ts + labels.ts ← exportReportToPdf (snapshot + branding + labels → ExportSession, rasters one by one, Blob of the parts, abort on unmount), defaultPdfLabels (25 keys); the tests' in-process import lives in tests/helpers/pdfImport.ts (the module's reader) │ │ └─ branding.ts + browserRasterizer.ts ← bundled src/assets/brand logos (?inline / ?raw) → Branding; Image/canvas Rasterizer adapter │ ├─ lib/{dates,id,assert,supabase}.ts ← supabase.ts: getSupabaseClient() | null │ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first │ └─ main.tsx ├─ tests/ │ ├─ setup.ts │ └─ unit/*.test.ts ├─ e2e/ ← Playwright (V1-1.3): playwright.{ui,shell}.config.ts, support/{browser,sandbox,shell,records}.ts, ui/*.spec.ts, shell/*.spec.ts, harness/dialog.{html,tsx} (dev server only, never built) ├─ docker/ │ ├─ entrypoint.sh ← injects env.js at container start │ └─ nginx.conf ← SPA fallback + PORT envsubst ├─ docs/ │ ├─ ANNOTATION-RENDERING.md ← annotation layer contract (attributes, styles, colours) │ ├─ PDF-FORMAT.md │ ├─ design/ ← VALIDATED graphic references (README.md + faunosteo-etape7-maquettes-validees.png); follow before proposing UI │ ├─ faunosteo-audit/ ← audit of the current system (frozen at 83e40af) │ ├─ development/ ← SaaS implementation plan, WORKSPACE.md │ └─ history/superpowers/{specs,plans}/ ← 2026-05 design records (docs/superpowers is purged by gitflow finish) ├─ eslint.config.js, index.html, package.json (@faunosteo/app) ├─ tsconfig*.json, vite.config.ts, vitest.config.ts │ (end of apps/app) │ (packages/domain and packages/anatomy deleted at R5.7: their sources resolve at 756b7ef, crates/core/tests/curation/{FILES,LEDGER}.tsv) ├─ packages/supabase/ ← @faunosteo/supabase │ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds) │ ├─ src/{records,workspaces,clients,species,animals,relations,field-limits}.ts ← V1-1 record access (closed RecordFailure kinds, keyset pages), D-R7 bounds │ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar` = `pnpm db:sandbox avatar-e2e`), fails on any target but the sandbox gateway and database │ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test ├─ supabase/ │ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts │ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2, profiles_professional, files_foundation (assets, buckets, avatar policies, purge queue, RPCs), workspaces (V1-1.1: personal workspace per account, access helpers), clients (V1-1.2: client RPCs and search, write budget per workspace), animals_relations (V1-1.4: species rows, animals, relations with history and voiding, their RPCs and reads) │ ├─ seed/anatomical-sheets/equine/ │ │ ├─ legacy-sources/ ← the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input, never edited) │ │ ├─ legacy-import/ ← GENERATED baseline: document, id map, IMPORT-REPORT, SVG copies (no SQL) │ │ ├─ curation/{changes,references}.json ← AUTHORED changeset + references registry (never generated) │ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql │ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy ├─ packages/README.md ← shared packages index ├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + CoreExportSession (R4.6) + Node source, pkg/ shipped and pkg-proofs/ (built, git-ignored, BUILD_STAMP), ts-rs types (committed), frozen N-1 reader (tests/n-1), tests ├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root) │ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), curation/{text,ids,prettier_json,markdown,report_guard,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL, CHANGELOG, REVIEW-REPORT, review drawings), curation/upload.rs (R5.5, feature `upload`: the upload rules, pure) + bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`) + bin/upload_sheet_assets/ (`pnpm assets:upload`, ureq; the three tools allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, fixtures/svg/hostile); no I/O, no clock (lint-enforced) │ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle; trap exports in the proofs build only) │ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh ├─ scripts/{rust-env,rust-check,wasm-build,check-all,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`) ├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin ├─ docker-compose.yml ← `app` service; `worker` service under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`) ├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proofs (R0 module, R2 app image: app-image.sh) ├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) ├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy) ├─ .claude/{tasks/TODO.md,memory/,audits/} ├─ Dockerfile, docker-compose.yml, docker/ ├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json ├─ package.json (workspace root), pnpm-workspace.yaml, pnpm-lock.yaml ├─ CLAUDE.md, README.md, DEPLOY.md, CHANGELOG.md, LICENSE ``` --- ## Architecture ``` User interaction → React routes (BrowserRouter) → Zustand store (reportStore) → Components read store via selectors (no prop drilling) Sheet loading (Rust core, RUST.md §8) → useSheet(speciesId) → SheetProvider (bundled: virtual:faunosteo-sheet, SHEET_BUNDLE=draft) → raw payload → coreRuntime().ready() (lazy; core_unavailable + retry on failure) → SheetHandle(payload): strict parse of the document and migration map, index → index_data → SheetIndex (tables only) + ops (sheet-bound core calls) SVG interaction → AnatomyCanvas builds the view once per (sheet, view): index.canvasSvg(view) = core `view.canvas` (the drawing read once at sheet load: prescan caps → roxmltree → allowlist → reference graph; framed + annotation layer) → DOMParser → importNode; data-state restyled in place; a failed build shows the degraded notice with a retry → delegated click on [data-anno-id] → sheet.ops.zoneClick(observation, id) (one core call: decision + new observation) → open_view → DetailModal (same drawing, view_box crop, or the view's own asset) → open_vertebra_picker (initial selection from the core) / open_laterality_picker (sides present) → pickers → vertebra.select per tap, vertebra.sync / zone.add_sides on confirm → updateObservation() in store → toggle / remove_both_sides → the core's observation → updateObservation(); findings picker → finding.toggle PDF export (app side: apps/app/src/pdf; writer: crates/core/src/pdf/write, RUST.md §10.4 to §10.8) → exportReportToPdf(report, index, { locale, signal }) → index.ops.snapshot(report) (core: archive.snapshot) + loadBranding() (4 logos bundled at build time, no network) + defaultPdfLabels (labels.ts) → openExportSession(runtime, ExportInput JSON): the core checks the input (branding and labels schemas, snapshot gate through the SVG reader, sheet match, page caps), builds the envelope under 16 MiB, opens the file (Info, fonts) → loop session.next(): the SVG logos, then each observation's views (main first), composed by the core (R3 compose_highlight, 1200 px wide) → browserRasterizer under Promise.all → rasterFailed in rejection order, addRaster in request order (a view is decoded and its XObject written on arrival, PNG and planes dropped; a PNG the decoder refuses is the view's warning) → session.finish(): conclusion page, footers, pages, attachment (osteo-report.json, Keywords faunosteo-archive/1), self-check by the R4 reader → the file in parts → new Blob(parts) to EditorRoute → browser download, alert naming failed logo slots / views; free() in finally → a trap poisons the runtime as any core call; a session of a dropped instance answers core_unavailable; leaving the editor aborts and frees → export_from_envelope (cargo only) re-exports an archive from its own snapshot, branding and labels (no sheet) PDF import (R4.3, RUST.md §10.5; the core's reader `crates/core/src/pdf/read`, never a PDF library) → HomeRoute: routing on the first KiB and the size pre-checks → startImport (core/worker/controller) → a module worker created for the file (import.worker.ts, handler.ts): the compiled module posted by the page, a SheetHandle of the bundled sheet, the file streamed in chunks into the module's memory (FileBytes), `import_pdf_bytes` → in the core: byte scan for the EmbeddedFile stream (BLK-009: no object-graph parse): named osteo-report* first, capped inflation (16 MiB budget shared by the candidates), JSON prescan (depth, value count OD-3), the JavaScript-path decoding (`json_js`), then archive.import: layered reading (report: v3 as is, v2 migrated, else incompatible_version; envelope metadata tolerant, snapshot/branding/labels strict → archive kept or snapshotRejected) + rebase on the loaded sheet (unresolved flags, labels kept), one call → the settlement mapped by core/worker/outcome.ts (closed kinds; timeout, crash and read error told apart: OD-5), the worker terminated → hydrateImport({ report, archive }) → one alert (archive_ok / snapshot_rejected / rebased / migrated) → navigate /editor; a rescue copy (JSON) follows the same worker path (`restore_copy_bytes`) Identity (Step 7, docs/development/IDENTITY.md) → AuthProvider: authStore.start() = client.auth.initialize() (PKCE code in URL) + onAuthStateChange → signed_in → fetchOwnProfile + fetchOwnPlatformRoles; localeSync applies profiles.locale, saves switches → /login /signup /forgot-password /reset-password /auth/callback (packages/supabase auth wrappers, AuthFailure kinds) → RequireAuth guards /app/* (→ /login?next=), AppLayout (sidebar / top bar / drawer), Dashboard, Account (updateOwnProfile) → no Supabase configured: status unavailable, auth screens show a notice, local tool unchanged Files and avatar (Step 8 / R1, docs/development/STORAGE.md) → AvatarSection: pick → avatarTransport (sniff jpeg/png/webp, bitmap → canvas ≤ 1024 → JPEG) → preview (no request) → save: rpc begin_avatar_upload (row pending_upload, server-built keys) → storage upload at the quarantine key (INSERT policy) → rpc confirm_asset_upload (uploaded) → poll own assets row 1 s ≤ 30 s → clean: download under the SELECT policy → blob URL in authStore → worker (container faunosteo_worker, service key): claim_avatar_jobs (lease token) → GET quarantine → decode child (sandbox, 512² WebP) → POST clean object (upsert) → complete_avatar_job (previous clean → deleted, enqueued 48 h) → DELETE quarantine → mark_quarantine_purged → refusals: reject_avatar_job(closed code); sweeper: expire_pending_uploads, claim_purges/ack_purge, claim_quarantine_leftovers → remove_avatar: rows → deleted, objects purged after the grace; a deleted / superseded row never completes (status + token guards) Runtime config → Docker entrypoint writes env.js (window.__APP_CONFIG__) → index.html loads env.js before bundle → src/config/env.ts reads window.__APP_CONFIG__ → VITE_APP_* → defaults → ConfigProvider exposes via React context → appConfig.supabase (url + anon key) or null → lib/supabase.ts lazy client Database (Supabase) → schemas: public (exposed, RLS on every table) / private (helpers, triggers) / audit (append-only) → auth.users insert → private.handle_new_auth_user() → public.profiles row → platform roles: public.profile_roles written only by grant_platform_role / revoke_platform_role (security definer, actor checked via private.is_platform_*; every call logged by private.log_event) → tests: supabase/tests/*.sql (pgTAP) via PGlite in CI check job and `supabase test db` ``` --- ## Project conventions ### Language split - UI strings: bilingual FR/EN — all user-facing text goes through the i18n system (see below) - Code: English (variable names, function names, comments, docs) - Never mix: no French variable names, no raw French/English string literals in JSX — use `useT()` ### Identity strings - NEVER hardcode APP_SITE_NAME, APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE - Always read from ConfigProvider via useConfig() - src/config/env.ts is the only place with defaults ### Design references - `docs/design/` holds the owner-validated mockups (Step 7 file = target for the whole SaaS shell: sidebar entries, dashboard tiles, Mon compte tabs, mobile tab bar). Any new screen follows them; elements they show that no step has built yet are listed in `docs/design/README.md` with their owning step. A redesign needs a new validated file there first. ### Component stubs - Scaffold stubs render
ComponentName placeholder
- Replace stub body entirely when implementing — no partial edits on stubs --- ## Exceptions to global rules - **React SPA**: explicit exception — this is a practitioner tool, not a public website. No indexing needed. SPA is correct. (See BDR-001) - **No API versioning**: no hand-written HTTP API. Supabase exposes tables/RPC through PostgREST; breaking changes are handled by new migrations and RPC names, not URL versions. - **80-char line limit**: relaxed to 100 for TypeScript generics and long Zod chains. --- ## Rust by default (rule adopted 2026-10-12, BDR-043) Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (validated with the amendments of Annex C). Done: R0, R1 (worker), R2 (domain core used by the app, `docs/development/RUST.md` §8), R3 (anatomy core: SVG reader, layer, composition; editor canvas on it, RUST.md §9; validated and merged 2026-10-17), R4 (PDF core, RUST.md §10; merged 2026-10-21). R5 (pipeline, RUST.md §11: R5.1 to R5.7, the TypeScript packages deleted; merged 2026-10-25, not a production authorisation); release 0.2.0 unaffected. - Any logic that can run in Rust with no significant loss (features, UX, graphics, data compatibility, security, reliability, useful performance, resources, portability, maintainability, operations) is written in Rust: native for services, jobs and tools, WebAssembly for the browser. Equivalence suffices; "already in TypeScript", "more work" and "no performance gain" are never reasons to keep TypeScript. - Kept as is: React + TypeScript for UI, DOM, routing, Zustand stores, display formatting and vendor-SDK glue (supabase-js); UI form schemas (Zod, i18n keys) and dictionaries; Tailwind; PostgreSQL/SQL + RLS; Supabase Auth and Storage; Vite/ESLint tooling. A component kept in TypeScript needs the concrete constraint recorded in the review's exception table (Part II). - New business logic (rules, data transformations, parsers, validators, jobs, services, rule mirrors of SQL) is designed in `crates/` first and reached from TypeScript through the wasm facade; Edge Functions are not used. Boundary rules: "Rust computes, TypeScript reads" (review Part III.3: coarse calls, JSON strings, sheet handle, closed error kinds, ids and time injected, no call in a render path). - Existing code migrates along the review's phases (R0–R5), each with oracles frozen with the old code before the switch and a consumer-driven deletion of the TypeScript it replaces; two implementations never outlive the phase that switches the last consumer. --- ## Key dependencies | Package | Purpose | |---|---| | react 19 | UI framework, automatic memo + concurrent rendering | | react-dom 19 | DOM renderer | | react-router-dom 7 | Client-side routing (BrowserRouter) | | vite 7 | Build tool, HMR, ESM-native | | @vitejs/plugin-react-swc | Fast React transform via SWC | | typescript 5 | Type safety, strict mode | | tailwindcss 4 | CSS-first utility framework | | zustand 5 | Lightweight global state | | zod 3 | Schema validation + type inference | | motion 11 | Animations (modals, toasts, observation cards) | | vitest 3 | Test runner | | happy-dom | DOM environment for tests | | @testing-library/react | Component testing utilities | | @testing-library/jest-dom | Custom DOM matchers | | eslint 9 | Linting (flat config) | | @supabase/supabase-js 2 | Typed client (packages/supabase) | | supabase (CLI) 2.120 | Local stack, migrations, pgTAP runner, type generation | | @electric-sql/pglite 0.3 | PostgreSQL 17 in WASM: runs the pgTAP suite without Docker | | prettier 3 | Code formatting | --- ## Workflow expectations - Run `pnpm typecheck && pnpm test:run` before every commit; after any change under `crates/core` or `crates/wasm`, `pnpm wasm:build` first (the suites refuse a missing or stale module: BUILD_STAMP). - Contract changes (`crates/core/src/domain`) require the ts-rs types regenerated and committed, all callers updated, the N-1 reader test green, and a version bump if breaking. `apps/app/src` never imports `@faunosteo/domain` (ESLint). - Annotation rendering changes require updating docs/ANNOTATION-RENDERING.md first. - Never modify the legacy sources under `supabase/seed/anatomical-sheets/equine/legacy-sources/` — they are the importer's input (the user's historical files). - Ask before any change to the readers of user data: `crates/core/src/domain/{archive/read,report/rebase,report/read,session}.rs` and the PDF reader `crates/core/src/pdf/{read,json_js,import}.rs` (the TypeScript originals `readReportArchive`, `readArchiveDocument`, `readAttachedDocument`, `rebaseReportOnSheet` left with `packages/pdf` at R4.8; the frozen N-1 copies under `packages/core-wasm/tests/n-1` are never edited); archive readers never drop a schema version (envelope v1, Report v2/v3, sheet document v2). - Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040). - After PDF roundtrip tests fail: check the attachment bytes (the N-1 scanner reads them in the envelope suites), then the layered reader (report first, envelope metadata, snapshot/branding/labels), then the core's inflation (`pdf/read/inflate.rs`). Goldens under `apps/app/tests/fixtures/goldens/step6` and the R4 digests under `goldens/r4` are never regenerated without a user decision. - Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install. - Rust: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes. - Storage or worker change: `pnpm db:sandbox avatar-e2e` (the avatar suite `packages/supabase/tests/e2e` and the real worker on the throwaway stack) in addition to `pnpm worker:test`; `pnpm e2e:avatar` is its alias (owner decision 2026-11-02: no avatar e2e against DEV, `scripts/avatar-e2e.sh` removed); `docker compose --profile worker` serves the worker from `.env.worker` (never the app `.env`). - SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test` on the real stack when Docker is available; regenerate types (`pnpm db:types`). ## Commit message convention Conventional Commits format. Subject ≤72 chars, imperative mood, no trailing period. Allowed scopes: `schema`, `store`, `anatomy`, `pdf`, `editor`, `home`, `new`, `ui`, `config`, `species`, `i18n`, `docker`, `docs`, `tests`, `chore`, `app`, `workspace`, `ci`, `supabase`, `domain`, `worker`, `public-web`. Examples: - `test(schema): cover Report version literal` - `feat(store): implement addObservation` - `feat(anatomy): parse data-anno-id from SVG` ## Path-scoped rules Project rules live in `.claude/rules/.md` and load on Read of a file matching their `paths:` (never at session start): docker, i18n, annotation-rendering, schemas, stores, pdf, sheet-content, database, environments, storage, sheet-model.