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.
222 lines
12 KiB
Markdown
222 lines
12 KiB
Markdown
# Migration strategy: current SPA → SaaS architecture
|
|
|
|
Status: Step 0 deliverable, 2026-10-08. Describes *how* the existing code
|
|
evolves without a big-bang rewrite. The step-by-step schedule is in
|
|
`IMPLEMENTATION_PLAN.md`; this document explains the mechanics behind it.
|
|
|
|
## 1. Principles
|
|
|
|
1. **Adapters, not rewrites** (architecture principle 15). Every module that
|
|
survives gets an interface at its edge; old and new implementations coexist
|
|
behind it until the old one has no caller.
|
|
2. **Characterisation tests first.** No module is refactored before its
|
|
observable behaviour is pinned by tests on real data (`TEST_STRATEGY.md` §2).
|
|
3. **The canonical sheet document is pure code before it is a table.** It can
|
|
be built, tested and used by the PDF pipeline with no database, which
|
|
decouples the anatomy refactor from the Supabase foundation.
|
|
4. **One identity space change, done once.** Legacy `data-anno-id` values are
|
|
mapped to stable ids by the importer, the mapping is stored in the seed
|
|
sheet, and no runtime code ever consults legacy ids again.
|
|
5. **Delete at a named step.** Each replaced module has the step at which it is
|
|
removed written in `REPOSITORY_MIGRATION_MAP.md`.
|
|
|
|
## 2. `reportStore`
|
|
|
|
Today: Zustand store holding `Report | null`, 14 actions, a `subscribe` that
|
|
mirrors every change to `sessionStorage['osteo:draft']`, restore on boot via
|
|
`ReportSchema.safeParse` (`reportStore.ts:42-56`, `159-167`).
|
|
|
|
Evolution in three moves:
|
|
|
|
| Move | Change | Behaviour preserved by |
|
|
|---|---|---|
|
|
| A. Split actions from persistence | Actions become pure functions on a report document (`addObservation(doc)`, `updateObservation(doc, i, obs)`...). The store calls them. The `subscribe` mirror moves behind `ReportPersistence` with `sessionStoragePersistence` as the only implementation. | `state.reportStore.*`, `state.draftMirror`, `state.reportStore.restore` tests unchanged |
|
|
| B. Document v3 | The store holds a v3 document (`annotationId`/`viewId` zones, region codes, `anatomicalSheetVersionId`, identity snapshots, `localAnnotations`). A `v2ToV3(report, sheetSeed)` adapter in `packages/domain` converts legacy drafts and PDF attachments using the seed's legacy id map. | adapter tests on golden v2 fixtures |
|
|
| C. Server persistence | `supabasePersistence` saves `current_document` through an `autosave_report` RPC (throttled, returns revision no), loads by id, subscribes to remote changes. `outboxPersistence` (IndexedDB) wraps it for offline. Sync state exposed to the UI. | contract tests shared by all three adapters |
|
|
|
|
`activeObservationIndex`, `setActiveObservation` and the per-observation
|
|
UI state stay client-only.
|
|
|
|
## 3. Anatomy domain
|
|
|
|
Today: four sources with no common object (manifest TS, two SVG files
|
|
fetched from `public/`, catalog JSON bundled), link by fuzzy label at render
|
|
time (audit 02 §1, 06 §1).
|
|
|
|
Evolution:
|
|
|
|
1. **Canonical document type** in `packages/domain`: `AnatomicalSheetDocument`
|
|
(Zod). `vertebral_config` is an *ordered list* of regions
|
|
`{ code, label_fr, label_en, count }`, not the fixed `C/T/L/S/Cd` object
|
|
(removes the hard-coded five-region assumption, §23.2; the architecture's
|
|
own §7.2 example still shows the fixed object, flagged in
|
|
`OPEN_QUESTIONS.md` C1).
|
|
2. **Legacy importer** in `packages/anatomy/legacy`: input = SVG texts +
|
|
manifest-like descriptor + catalog JSON; output = canonical document +
|
|
assets list + `legacy_id_map`. It reuses `parseSvgBones`, `zoneMatch`
|
|
(once, to propose `annotation_finding_map`), `regionFromLabel` (once, to
|
|
set `region_code` on spine annotations). It must reproduce every special
|
|
case of audit 07: `vertebral-precision`, `bilateral`, `opens-detail`
|
|
trigger without name, detail view with its own id space, `ssb-dysfunctions`
|
|
duplicate category id under `sphenoid`, node ids unique only among
|
|
siblings, `anamnesis` three variants, missing `description_en`.
|
|
3. **Stable ids**: UUID v4 per annotation, view, category; `legacy_id` kept
|
|
on each annotation for the seed only. Finding node ids stay as authored
|
|
(unique among siblings) because `Finding.path` is anchored at the zone;
|
|
a `node_uid` can be added later without breaking paths.
|
|
4. **Renderer**: given a view (SVG text) and the document, emits the
|
|
`data-anno-*` attributes from the document (not from the file), so
|
|
`AnatomyCanvas` and `parseSvgBones` keep working. The SVG asset becomes a
|
|
drawing; the annotations are data. For the equine seed, annotations are
|
|
initially the same `<circle>`/`<polygon>` elements present in the files;
|
|
the renderer may inject them from `geometry` instead once the editor
|
|
writes geometry.
|
|
5. **Runtime link**: `ObservationCard` resolves the findings subtree through
|
|
`annotation_finding_map`; `matchZoneFindings` is no longer imported by
|
|
`src/`. A test asserts that.
|
|
6. **Registry removal**: `getSpecies()` callers (`EditorRoute`, `export.ts`,
|
|
`observationPage.ts`, `SvgEditorRoute`, `AnimalForm`) switch to a
|
|
`SheetProvider` interface (`getVersion(id)`), first implemented over the
|
|
seed document bundled in the app, then over Supabase. `registry.ts` and
|
|
`import.meta.glob` are deleted when the bundled implementation goes.
|
|
|
|
## 4. PDF
|
|
|
|
Today: `exportReportToPdf(report, { locale })` re-fetches SVGs from
|
|
`public/`, re-parses them for labels, reloads the catalog through the
|
|
registry, rasterises in the browser, attaches the raw `Report` JSON.
|
|
|
|
Evolution:
|
|
|
|
1. Signature becomes `exportReportToPdf(doc, sheetSnapshot, branding, { locale })`.
|
|
Labels come from `sheetSnapshot.annotations`; views from
|
|
`sheetSnapshot.views` (+ SVG text); zone names for findings from
|
|
`sheetSnapshot.finding_tree`. No fetch, no registry.
|
|
2. Attachment v3: `{ attachment_version: 3, report_document, sheet_version_ref:
|
|
{ sheet_id, version_id, version_number }, sheet_snapshot: <subset needed
|
|
to render>, exported_at, locale }`. Filename still starts with
|
|
`osteo-report` (import compatibility). Size: equine SVGs are 142 KB + 136 KB
|
|
and the catalog 170 KB; Flate keeps the attachment under 200 KB.
|
|
3. Import v3 validates the attachment, then the server import RPC checks
|
|
ownership, sheet version existence (or recreates a *snapshot-only*
|
|
read-only version when the sheet is gone, which is how rule 8 "historical
|
|
data restorable" is honoured), quota, and inserts.
|
|
4. Import v2 (current PDFs) goes through `v2ToV3` with the seed legacy map.
|
|
Whether that path is production or dev-only depends on `OPEN_QUESTIONS.md`
|
|
Q1. CLAUDE.md's "ask before changing `importReportFromPdf` /
|
|
`extractReportJson`" is honoured as an explicit confirmation gate inside
|
|
the PDF step.
|
|
5. Branding (`header.ts`, `footer.ts`, `logo.ts`) takes a `Branding` object
|
|
(platform + tenant). Hard-coded `faunosteo.com`, `zenquality.fr`,
|
|
Instagram links move into that object.
|
|
6. Server-side PDF stays out of scope until a `Rasterizer` interface exists;
|
|
`svgToPng` is the browser implementation.
|
|
|
|
## 5. SVG editor
|
|
|
|
Today: 1858-line vanilla DOM tool inside `useEffect([locale])`, DOM is the
|
|
database, export = serialize DOM (audit 03).
|
|
|
|
Strategy: **not ported, replaced**, in this order:
|
|
|
|
1. Write the functional reference as tests against the canonical document
|
|
(one test per operation of audit 03 §2: load, select, create point,
|
|
create polygon, edit names/category/laterality/radius/opacity, drag,
|
|
vertex insert/delete, delete, category add/rename/colour/delete/special,
|
|
detail trigger, export).
|
|
2. Build the new editor on `apps/app` with a proper model
|
|
(`SheetEditorStore` in Zustand: document + selection + mode + undo stack),
|
|
rendering through the same `AnatomyCanvas` renderer. Features the old tool
|
|
lacks and the architecture requires: create detail view from a selected
|
|
zone (bounding box + margin → `view_box`, child view with
|
|
`parent_view_id`), vertebral configuration editing, draft/publish flow,
|
|
stable ids.
|
|
3. Keep `/svg-editor` reachable until the reference tests pass on the new
|
|
editor, then delete `SvgEditorRoute.tsx`, `svg-editor.css` and the
|
|
`svg_editor.*` i18n keys in one commit.
|
|
|
|
Known traps carried from the audit: `applyEdit` strips `data-anno-category`
|
|
from detail triggers, which the app parser refuses (audit 10 C8); category
|
|
slugs with degraded accents are opaque ids and must be preserved verbatim by
|
|
the importer; `fixDuplicateIds` renames ids by category, which would break
|
|
`boneId` references, so the importer must run on the *committed* files, never
|
|
on an editor re-export.
|
|
|
|
## 6. Findings (pathology) editor
|
|
|
|
Today: static `public/pathology-editor.html`, hard-coded `SPECIES_CONFIG`,
|
|
inline matcher copy, download-only output, no Zod validation (audit 05 §3).
|
|
|
|
Strategy: its tree-editing behaviour (add root category, add child, edit,
|
|
delete with descendant count, sources rows, id generation by slug with `-2`
|
|
suffix) becomes the "findings" panel of the merged editor, operating on
|
|
`finding_tree` of the same document, with Zod validation before save and the
|
|
explicit `annotation_finding_map` edited in the same panel (click an
|
|
annotation → see/assign its finding zone). Missing abilities listed in audit
|
|
05 §3.6 (rename/delete zone, reorder, move node, edit `scope_disclaimer`)
|
|
are added here. The static file and the `public/species/equine/pathologies.json`
|
|
copy are deleted at the same step as the SVG editor. If an external domain
|
|
expert uses the static tool today (`OPEN_QUESTIONS.md` Q4), it stays
|
|
deployed read-only one release longer.
|
|
|
|
## 7. i18n
|
|
|
|
Today: flat FR/EN dicts in `src/i18n`, parity test, `useT` hook; 76 inline
|
|
keys in `pathology-editor.html`.
|
|
|
|
Evolution: move to `packages/i18n` when a second consumer exists, split
|
|
dictionaries (no React) from `useT` (React), add namespaces for new domains
|
|
(`clients.*`, `agenda.*`, `billing.*`, `community.*`, `admin.*`) keeping the
|
|
`<area>.<key>` convention and the parity test. Sheet content (zone names,
|
|
finding labels, descriptions) stays data inside the document, bilingual by
|
|
field, never dictionary keys. Emails rendered by the worker use the same
|
|
dictionaries. Locale persists in `profiles.locale` and still in
|
|
`localStorage` for the anonymous public site.
|
|
|
|
## 8. Species and seed migration (architecture §23.3)
|
|
|
|
```text
|
|
public/species/equine/Horse.svg + Horse_head.svg + src/domain/species/equine/pathologies.json
|
|
│ legacy importer (packages/anatomy/legacy), deterministic
|
|
▼
|
|
supabase/seed/anatomical-sheets/equine/v1/
|
|
document.json canonical sheet document (stable ids, explicit mapping, region codes)
|
|
legacy-id-map.json old data-anno-id → annotation id, old detail key 'head' → view id
|
|
assets/ the two SVG files, byte-identical to public/ (checksums recorded)
|
|
│ seed script (idempotent)
|
|
▼
|
|
anatomical_sheets "Faunosteo / Cheval / Fiche anatomique officielle"
|
|
anatomical_sheet_versions v1, published, immutable
|
|
storage: anatomical-sheets/<sheet-id>/<version-id>/<asset-id>/Horse.svg ...
|
|
```
|
|
|
|
Normalisations performed once, logged in the seed report (§23.5): duplicate
|
|
category id `ssb-dysfunctions` under `sphenoid` (kept as-is or renamed per
|
|
`OPEN_QUESTIONS.md` Q9), degraded category slugs (kept verbatim as ids,
|
|
labels taken from `data-anno-category-name` when present), missing
|
|
`description_en` (left empty), detail trigger `zone-mpby55kd` (becomes a
|
|
`detail-trigger` annotation with no finding mapping), `Horse_head.svg` as a
|
|
separate asset or a `view_box` on the main asset (Q5).
|
|
|
|
## 9. Data and compatibility rules during the transition
|
|
|
|
- Report v2 drafts in `sessionStorage` are converted on first load after the
|
|
v3 step; failure to convert keeps the draft untouched and shows a message.
|
|
- PDF v2 import remains available at least until the first production
|
|
release of the SaaS (dev adapter mandatory, production support per Q1).
|
|
- The `/species/equine/*` public paths keep being served until the three
|
|
consumers (report editor, SVG editor, pathology editor) have moved; the
|
|
nginx `no-cache` rule is removed with them.
|
|
- No step deletes data; soft delete and revisions only. Physical deletion is
|
|
limited to sheet-version garbage collection under the four preconditions
|
|
of rule 7 (§16).
|
|
|
|
## 10. Rollback
|
|
|
|
Each step is a feature branch merged into `develop` behind a working state.
|
|
Database steps are forward-only migrations with a rehearsed `supabase db
|
|
reset` on staging; rollback of a released DB step is a new migration
|
|
(contract phase), never a revert of an applied one. Frontend steps that
|
|
switch persistence keep the previous adapter selectable by runtime config for
|
|
one release.
|