Eight documents under docs/development/ confronting the approved business architecture with the audited code: 27-step plan, repository migration map, domain map, frontend/backend architecture, migration and test strategy, open questions. Reference document placed at the repository root.
17 KiB
Repository migration map
Status: Step 0 deliverable, 2026-10-08. Branch develop at 2ae1e48.
Sources: faunosteo-business-architecture.md (target), docs/faunosteo-audit/
(current behaviour, audited at 83e40af), direct reading of src/, public/,
docker/, tests/, scripts/.
Verdict vocabulary:
| Verdict | Meaning |
|---|---|
| KEEP | Used as-is in the target, possibly moved into a package |
| REFACTOR | Same responsibility, internals or contract change |
| REPLACE | A new implementation takes over; the old one is deleted at a named step |
| REMOVE LATER | Dead in the target; deleted once nothing imports it |
"Weight" is the importance of the area for the migration: HIGH means the SaaS cannot ship without migrating it, LOW means it is cosmetic or self-contained.
1. Application shell (src/app, src/config, src/main.tsx)
| File | Responsibility | Depends on | Weight | Verdict | Notes |
|---|---|---|---|---|---|
app/App.tsx |
BrowserRouter, 6 routes, footer toggle | routes, ConfigProvider | HIGH | REFACTOR | Routes move under /app/* with an auth guard; legacy routes redirect during transition. |
app/routes/HomeRoute.tsx |
New report / import PDF entry | pdf/import, reportStore | MEDIUM | REPLACE | Becomes /app/dashboard; PDF import becomes a server-validated flow (quota, ownership). |
app/routes/NewReportRoute.tsx |
Practitioner / animal / owner form, initReport() |
reportStore, practitionerCache, report forms | MEDIUM | REPLACE | In the target a report is created from an Animal record and a sheet version, not from free-text identity fields. |
app/routes/EditorRoute.tsx (552 lines) |
Report editor: loads SVG + detail SVGs, click chain onZoneClick (detail → fallback observation → spine → bilateral → toggle), export |
anatomy/*, species registry, reportStore, spineZones, pdf/export, components | HIGH | REFACTOR | The click chain is the core clinical behaviour and has zero tests (audit 13 §4). Extract it into a pure "zone interaction" service before touching persistence. Asset loading (loadSvg('/species/...')) is replaced by sheet-version content. |
app/routes/SvgEditorRoute.tsx (1858 lines) |
Vanilla DOM SVG annotation tool wrapped in useEffect([locale]) |
species registry, localeStore, i18n, svg-editor.css | HIGH | REPLACE | Replaced by the structured Anatomical Sheet editor (plan step "Editor merge"). Kept running untouched until then. Extraction candidates listed in audit 11 §7. |
app/routes/EditorsRoute.tsx |
Links to the two editors | i18n | LOW | REMOVE LATER | Disappears with the merged editor. |
app/routes/NotFoundRoute.tsx |
404 | i18n | LOW | KEEP | |
app/providers/ConfigProvider.tsx, config/env.ts |
Runtime identity config (window.__APP_CONFIG__ > VITE_APP_* > defaults) |
entrypoint.sh | MEDIUM | REFACTOR | Same mechanism extended with supabaseUrl, supabaseAnonKey, publicWebUrl. Anon key is public by design; service keys never enter this path. |
2. Domain (src/domain)
| File | Responsibility | Depends on | Weight | Verdict | Notes |
|---|---|---|---|---|---|
schema/report.ts |
Report v2 (literal version: 2), NextAppointment |
observation, practitioner, animal | HIGH | REFACTOR | Becomes the report document schema v3: adds anatomicalSheetVersionId, localAnnotations, identity snapshots; drops free-text practitioner identity as source of truth. v2 kept as an input type for the adapter. |
schema/observation.ts |
Observation, ObservationZone (boneId, detailSourceId, vertebrae, side), Finding (zoneId, path, snapshots) |
zod | HIGH | REFACTOR | boneId → annotationId (stable id from the sheet), detailSourceId → viewId, VertebralRegionSchema enum → region code validated against the sheet's vertebral config. Finding gains nothing but is linked to the zone through the sheet's explicit mapping. |
schema/findings.ts |
Catalog schema: SpeciesFindings, ZoneFindings, recursive FindingNode, SourceRef |
zod | HIGH | KEEP | Becomes the finding_tree section of the canonical sheet document. snake_case retained (BDR-009). Add node-id uniqueness and schema_version checks that the current schema lacks (audit 05 §2.2). |
schema/animal.ts, schema/practitioner.ts |
Free-text identity blocks inside the report | zod | MEDIUM | REPLACE | Animals and practitioners become DB entities. The report document keeps an identity snapshot for PDF reproducibility, so a reduced form of these schemas survives as snapshot sub-schemas. |
species/types.ts (SpeciesManifest, VertebralFormula) |
Compiled manifest contract | findings | HIGH | REPLACE | Replaced by the canonical sheet document (views, annotations, vertebral config, finding tree). |
species/registry.ts |
import.meta.glob auto-discovery of manifests |
Vite | HIGH | REMOVE LATER | Vite-specific, bundle-time. Gone once sheets are DB rows. Deleted at the "Sheets in DB" step. |
species/equine/index.ts, vertebrae.ts, pathologies.ts, pathologies.json |
The implicit equine "sheet" (manifest, formula, catalog) | registry | HIGH | REPLACE | Become seed input for the official equine sheet v1. The files move to supabase/seed/anatomical-sheets/equine/ and are read by the importer, never by the runtime. |
3. State (src/state)
| File | Responsibility | Depends on | Weight | Verdict | Notes |
|---|---|---|---|---|---|
reportStore.ts |
Zustand store, actions, sessionStorage mirror osteo:draft, restore on boot |
schema/report, lib/id, lib/dates | HIGH | REFACTOR | Split into (a) pure reducer-style actions on a report document and (b) a persistence adapter interface. Current sessionStorage mirror becomes one adapter; Supabase autosave and IndexedDB outbox become two others. See MIGRATION_STRATEGY.md §2. |
localeStore.ts |
'fr' | 'en', persisted osteo:locale |
zustand | LOW | KEEP | Later also synced to profiles.locale. |
practitionerCache.ts |
localStorage prefill of practitioner block |
schema/practitioner | LOW | REMOVE LATER | Replaced by the authenticated profile. |
4. Anatomy (src/anatomy)
| File | Responsibility | Depends on | Weight | Verdict | Notes |
|---|---|---|---|---|---|
svgConvention.ts (parseSvgBones, getBoneIdFromEvent) |
DOM walk of data-anno-*, SvgConventionError |
DOM | HIGH | KEEP | Pure DOM, no fetch. Reused twice: by the seed importer (legacy SVG → canonical document) and by the runtime canvas (click delegation on data-anno-id, which the renderer re-emits from the canonical document). |
svgLoader.ts (loadSvg(publicPath)) |
fetch + DOMParser |
fetch | MEDIUM | REFACTOR | Becomes parseSvgText(text); the source (public path today, Storage signed URL or inlined content tomorrow) is passed by the caller. Four call sites (audit 01 §3). |
labels.ts, i18n/pickLocaleLabel.ts |
FR/EN fallback label | i18n | LOW | KEEP | |
types.ts (Bone, BoneState, SvgConventionError) |
Parsed element model | DOM | MEDIUM | REFACTOR | Bone is the legacy parsed shape. The canonical Annotation type (stable id, view id, kind, geometry, category id, laterality, special) lives in the domain package; Bone stays as importer input. |
5. Components (src/components)
| Folder / file | Responsibility | Weight | Verdict | Notes |
|---|---|---|---|---|
ui/* (Button, Card, Dialog, Input, Label, Select, Textarea, Badge, Chip) |
Primitives | LOW | KEEP | Move to packages/ui when a second app needs them (public-web). Not before. |
canvas/AnatomyCanvas.tsx |
Inline SVG, delegated click, data-state highlight, tooltip |
HIGH | REFACTOR | Accepts SVG text or a canonical view instead of a URL. Tooltip skips data-anno-opens-detail elements; keep that behaviour for "detail trigger" annotations. |
canvas/DetailModal.tsx |
Dialog around a detail AnatomyCanvas |
MEDIUM | REFACTOR | Generalised to any child view (parent_view_id), with a breadcrumb for nested views. |
observation/ObservationCard.tsx |
Zone badges, pickers per (tree.id, side), severity, comment; only runtime caller of matchZoneFindings (line 134) |
HIGH | REFACTOR | Replace the fuzzy match with the sheet's explicit annotation_id → finding_zone_id mapping. Everything else stays. |
observation/FindingsTreePicker.tsx |
Breadcrumb drill-down over a ZoneFindings subtree, emits Finding with snapshots |
HIGH | KEEP | Pure component on the tree; unchanged by the storage migration. |
observation/VertebraPicker.tsx |
Region tabs + chip grid from VertebralFormula; REGIONS hard-coded C T L S Cd |
HIGH | REFACTOR | Tabs come from the sheet's ordered region list (code, label FR/EN, count). |
observation/LateralityPicker.tsx, SeveritySelector.tsx, FreeTextFindingInput.tsx, ObservationList.tsx |
Pure UI | MEDIUM | KEEP | |
report/PractitionerForm.tsx, AnimalForm.tsx |
Free-text identity forms; AnimalForm lists getAllSpecies() |
MEDIUM | REPLACE | Replaced by profile data and an Animal/Client picker. AnimalForm may survive as the "new animal" dialog with species from DB. |
report/ReportHeader.tsx, ConclusionPanel.tsx, NextAppointmentPicker.tsx |
Report editing UI | MEDIUM | KEEP | NextAppointmentPicker later links to the Agenda domain. |
brand/* (AppHeader, Brand, Footer, LanguageSwitcher) |
Branding | LOW | KEEP | Tenant branding (practitioner/cabinet logo) injected via config later. |
6. PDF (src/pdf)
| File | Responsibility | Weight | Verdict | Notes |
|---|---|---|---|---|
export.ts (exportReportToPdf, buildZoneLabels, loadSpeciesFindings) |
Orchestrates pages, re-fetches SVGs and catalog from public/ and the registry at export time |
HIGH | REFACTOR | Inputs become (reportDocument, sheetVersionContent, branding, locale). No fetch of public/species, no registry. Labels come from the sheet document, not from a re-parse. |
import.ts, attachment.ts |
Load PDF, extract osteo-report*.json, version gate (!== 2 → typed error), Zod parse, 16 MiB inflate cap |
HIGH | REFACTOR | Attachment v3 carries report document + schema version + sheet version id + sheet snapshot. CLAUDE.md requires asking before changing these two files: that gate is part of the plan step, not bypassed. |
render/observationPage.ts (651 lines) |
Rasterises views, draws zone/findings sections; colorizedSvgString re-fetches the SVG |
HIGH | REFACTOR | Takes view SVG text and annotation ids from the sheet snapshot. Text sections unchanged. |
render/header.ts, footer.ts, logo.ts, linkAnnotation.ts |
Branding, hard-coded logos and URLs (faunosteo.com, zenquality.fr, Instagram) |
MEDIUM | REFACTOR | Branding becomes a parameter (platform + tenant). |
render/svgToPng.ts |
Image + canvas rasteriser |
MEDIUM | KEEP | Browser-only. Blocks any server-side PDF generation until replaced (resvg or similar). Server PDF is explicitly "later" in the architecture (§22.3). |
render/text.ts, conclusionPage.ts, constants.ts, fonts.ts |
Layout helpers, StandardFonts WinAnsi | LOW | KEEP | TTF embedding stays a separate improvement (EVAL-003). |
7. Lib (src/lib)
| File | Responsibility | Weight | Verdict | Notes |
|---|---|---|---|---|
zoneMatch.ts |
Fuzzy FR/EN label match SVG ↔ catalog (EN exact → FR exact → substring → Levenshtein 25 %) | HIGH | KEEP as migration helper, REMOVE from runtime | Moves to the importer. Runtime mapping is explicit (architecture §23.2, principle 5). Its inline copy in pathology-editor.html dies with that tool. |
spineZones.ts (regionFromLabel, findSpineZoneId, collectSpineVertebrae, syncSpineZones) |
Spine picker seed/confirm logic; region deduced from label roots | HIGH | REFACTOR | regionFromLabel is replaced by an explicit region_code on spine annotations in the sheet. collect/sync logic (BDR-019) is kept, keyed on that code. The importer uses regionFromLabel once to populate the code. |
id.ts, dates.ts, assert.ts |
Utilities | LOW | KEEP |
8. i18n (src/i18n)
| File | Weight | Verdict | Notes |
|---|---|---|---|
fr.ts, en.ts (flat dicts, parity-tested), index.ts, useT.ts, types.ts |
MEDIUM | KEEP | Moves to packages/i18n when public-web needs shared strings. The 76 inline keys of pathology-editor.html are folded in at the editor merge. Sheet content strings (zone names, finding labels) stay data, not dictionary keys. |
9. Static assets (public/)
| Path | Weight | Verdict | Notes |
|---|---|---|---|
public/species/equine/Horse.svg, Horse_head.svg |
HIGH | KEEP as seed input, stop serving at runtime | Never modified (CLAUDE.md). Read once by the importer; bytes uploaded to the anatomical-sheets bucket as assets of the official equine sheet v1. Horse_head.svg is a full copy of Horse.svg with a different viewBox (audit 04 §2): see OPEN_QUESTIONS.md Q5. |
public/species/equine/pathologies.json |
HIGH | REMOVE LATER | Second copy of the catalog, read only by pathology-editor.html. Dies with it. |
public/pathology-editor.html (1700 lines, zero src/ imports) |
HIGH | REPLACE | Kept working untouched until the editor merge step, then deleted. Its tree-edit logic is the reference behaviour for the findings panel of the new editor (audit 11 §7). |
public/env.js, favicon.svg, logo-horizontal.svg, assets/*.png, brand/*.png, Paws_in_harmony.svg |
LOW | KEEP | Platform branding. |
10. Scripts
| Path | Weight | Verdict | Notes |
|---|---|---|---|
scripts/scaffold-species.mjs |
LOW | REMOVE LATER | Writes schema_version '1.1' and a mixed canine/equine formula (audit 12 §1). Species become DB rows; a "new sheet" action in the editor replaces it. Not worth fixing. |
logos/generate-sizes.sh |
LOW | KEEP | Brand tooling, out of scope. |
11. Tests (tests/)
32 files under tests/unit/, 180 it( cases (audit 13; README says 174, stale). happy-dom, no e2e. KEEP and EXTEND. The untested areas that gate the migration (click chain, full PDF roundtrip with observations, real SVG ↔ catalog equality, opens-detail ↔ manifest coherence, zoneMatch parity, catalog copies parity) are the content of plan Step 1. See TEST_STRATEGY.md §2.
12. Docker, nginx, runtime configuration
| File | Responsibility | Weight | Verdict | Notes |
|---|---|---|---|---|
Dockerfile |
node:20-alpine build (pnpm 10.13.1 pinned, BLK-005) → nginx:1.31-alpine, non-root, port 8080 | MEDIUM | REFACTOR | Build context becomes the monorepo; builds apps/app only. Separate images for public-web and worker appear with those apps. |
docker/nginx.conf |
SPA fallback, /species/ no-cache, /assets/ immutable, /env.js no-store |
MEDIUM | REFACTOR | /species/ rule becomes dead once sheets are served from Storage. Add security headers (CSP, HSTS at the proxy) at the hardening step. |
docker/entrypoint.sh |
Writes env.js from APP_* env vars, escapes values, envsubst PORT |
MEDIUM | REFACTOR | Adds SUPABASE_URL, SUPABASE_ANON_KEY, PUBLIC_WEB_URL. Same escaping discipline (SEC-9). |
docker-compose.yml, .env.example |
Single app service |
MEDIUM | REFACTOR | Gains the self-hosted Supabase stack (or an external URL), public-web, worker. .env.example grows with placeholders only. |
DEPLOY.md |
1 vCPU / 1 GB VPS runbook | MEDIUM | REFACTOR | Self-hosted Supabase does not fit 1 GB (see OPEN_QUESTIONS.md Q2). |
13. Documentation
| File | Verdict | Notes |
|---|---|---|
docs/ANATOMY-SVG-CONVENTION.md |
REFACTOR | Out of sync with the parser (audit 10 I5: 7 "valid categories" that do not exist, linked/multi states removed). Becomes "Legacy SVG import convention", scoped to the importer. |
docs/PATHOLOGIES-FORMAT.md |
REFACTOR | Becomes the finding_tree section of the sheet document spec. |
docs/ADDING-A-SPECIES.md |
REPLACE | Species are created in the editor. |
docs/PDF-FORMAT.md |
REPLACE | 12-line placeholder today; written for attachment v3. |
docs/superpowers/* |
KEEP | Historical design records. |
docs/faunosteo-audit/ |
KEEP | Reference for the migration; frozen at 83e40af. |
docs/development/ |
NEW | This set. |
14. Git, hooks, memory
.githooks/, .claude/ are untouched by the migration. Note: the working tree
has uncommitted edits in .githooks/post-commit and .githooks/post-merge
(manual-push-mode fail-closed change) and the untracked
faunosteo-business-architecture.md. Neither is part of Step 0.
15. Summary by verdict
| Verdict | Areas |
|---|---|
| KEEP | parseSvgBones, findings schema, FindingsTreePicker, pickers, UI primitives, i18n, PDF render helpers, svgToPng, lib utils, tests, seed SVGs |
| REFACTOR | EditorRoute click chain, reportStore, report/observation schemas, AnatomyCanvas/DetailModal, ObservationCard (mapping), VertebraPicker, spineZones, PDF export/import/attachment/observationPage, Docker/nginx/entrypoint, ConfigProvider |
| REPLACE | SvgEditorRoute, pathology-editor.html, species manifest/types, HomeRoute/NewReportRoute, identity forms, scaffold-species, ADDING-A-SPECIES.md, PDF-FORMAT.md |
| REMOVE LATER | species/registry.ts, practitionerCache, EditorsRoute, public/species/equine/pathologies.json, runtime use of zoneMatch |