Files
faunosteo/docs/development/REPOSITORY_MIGRATION_MAP.md
bchanot ac60b24267 docs(docs): realign active docs on develop for P0
Roadmap section and step statuses in the plan, D-R9 Rust services in
place of Edge Functions and a Node worker, platform roles per BDR-026,
equine sheet draft-only, curation-only authoring until Step 17,
OPEN_QUESTIONS statuses and conflict resolutions, dated snapshot
notices on the Step 0 documents.
2026-10-25 17:12:37 +01:00

17 KiB

Repository migration map

Status: Step 0 deliverable, 2026-10-08. Branch develop at 2ae1e48. Snapshot notice (2026-10-25, P0): every REMOVE / REPLACE verdict below has been executed except practitionerCache.ts (still used by the local tool); the file paths, counts and the anatomical-sheets bucket name are those of 2026-10-08 (the bucket is anatomical-sheet-assets). Kept as the record of the starting point; CLAUDE.md holds the current map. 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/history/superpowers/* KEEP Historical design specs and plans (2026-05). Moved from docs/superpowers/, a path the gitflow lib purges at every finish (BDR-065).
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