Files
faunosteo/docs/development/REPOSITORY_MIGRATION_MAP.md
T
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

164 lines
17 KiB
Markdown

# 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` |