Files
faunosteo/CLAUDE.md
T
bchanot f924ad056d test(supabase): sheet-assets e2e on the sandbox only
pnpm e2e:sheet-assets is now an alias of pnpm db:sandbox sheet-assets-e2e:
gateway on 127.0.0.1:57800 (occupied port refused), the runner refuses any
URL but the sandbox gateway and any key not issued by the sandbox, before
building or any request; no DEV URL, port or key remains.
2026-11-02 00:09:02 +01:00

43 KiB
Raw Blame History

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; V1-1 merged into develop 2026-10-27, merge 9135d73: 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, applied to Supabase DEV 2026-10-27 by the owner procedure (SUPABASE.md §3.3); 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)). V1-2 contract (decisions O1-O23 ratified 2026-10-28, BDR-082; contract under the owner's final review, no implementation before the owner's go): docs/development/V1-2_ANATOMICAL_SHEETS.md, branch feature/v1-2-anatomical-sheets.


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.

# Development (DEV origin = this machine's LAN address, scripts/dev-env.sh; tests run from other devices)
pnpm dev               # Vite on http://<FAUNOSTEO_DEV_HOST>: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 <args>`
pnpm db:start          # start stack, apply migrations + seed; FAUNOSTEO_DEV_HOST=<ip> 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 <version> [<then>]|test-db|types [--check]|test|e2e-shell|verify-e2e|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 <dir>  # 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 <dir>  # 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 <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
pnpm assets:upload [--check] <seed folder>  # 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: that tool against the throwaway sandbox (= `pnpm db:sandbox sheet-assets-e2e`, gateway on 127.0.0.1:57800; upload, rerun, anon and wrong key, refused destinations); needs `pnpm db:sandbox up fresh`, refuses any other target
pnpm report:compare <pdf|dir>...  # 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-01)

Test commands

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 <spec> [--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

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 <dialog> 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), sheet_access_hardening + sheet_review_workflow (V1-2.1 M4, M5), sheet_verification_jobs (V1-2.3 M6: the worker's verdict RPCs, service role only)
│  ├─ 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; sheet/{size,keys,caps,review,report,verdict,preview,edit} since V1-2.2: server document measure, review groups and digests, the server verdict, PreviewSheet, the editor's commands, RUST.md §12), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize,clean},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, PreviewBuilder → PreviewSheet, clean_svg; trap exports in the proofs build only)
│  └─ worker/                                  ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; V1-2.3 `verify` sandboxed child (framed input → the core's `compute_verdict`) and `run --jobs sheet-verify` (verify_job, VerifyBackend: M6 RPCs + drawing downloads); 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` and `worker-verify` (V1-2.3, `run --jobs sheet-verify`) services 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-01: 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/<name>.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.