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.
208 lines
13 KiB
Markdown
208 lines
13 KiB
Markdown
# Frontend architecture (target)
|
||
|
||
Status: Step 0 deliverable, 2026-10-08. Proposal only; the repository is not
|
||
transformed by this document.
|
||
|
||
## 1. Starting point
|
||
|
||
The private application is a Vite 7 + React 19 SPA, TypeScript strict,
|
||
Tailwind v4, Zustand 5, Zod 3, pdf-lib, served by nginx from a Docker image.
|
||
Six routes (`/`, `/new`, `/editor`, `/svg-editor`, `/editors`, `*`) plus the
|
||
static `/pathology-editor.html`. No auth, no backend, state in
|
||
`sessionStorage`/`localStorage` (BDR-001, audit 01 §2).
|
||
|
||
The architecture document asks to keep this app "close to its working form"
|
||
(§21.1, §21.3) and to serve public SEO pages server-side (§21.2). Both are
|
||
compatible with the current code; neither requires a rewrite.
|
||
|
||
## 2. Is `apps/app`, `apps/public-web`, `apps/worker` right for this repository?
|
||
|
||
Short answer: yes for the three units, no for creating them all on day one.
|
||
|
||
| Unit | Verdict | Why |
|
||
|---|---|---|
|
||
| `apps/app` (Vite React, private) | Adopt at the first structural step | It *is* the current app. Moving it under `apps/` while it has 82 source files and 32 test files is cheap; doing it after packages and a second app exist is not. |
|
||
| `apps/public-web` (Next.js) | Adopt, but only at the "Public profile + public site" step | Nothing public exists before practitioner profiles. Creating an empty Next.js app earlier adds a toolchain to maintain with no deliverable behind it. |
|
||
| `apps/worker` (Node) | Adopt, but only at the "Agenda / Notifications" step | Until reminders, appointment expiry and calendar sync exist, every job can be a PostgreSQL function or `pg_cron` job inside Supabase (architecture §22.3 says "start with PostgreSQL-backed jobs"). |
|
||
|
||
Alternatives considered and rejected:
|
||
|
||
- **Single Next.js app for everything.** Rejected: rewrite of the editor and PDF pipeline, SSR brings no value to a clinical tool behind auth, contradicts §21.3.
|
||
- **Keep the app at the repository root, add `apps/public-web` beside it.** Rejected: path aliases (`@/*`), Docker build context, tsconfig includes and Vitest config would all special-case the root app; `pnpm-workspace.yaml` already exists at the root (it only holds `allowBuilds` today), so the workspace is one line away.
|
||
- **Astro for the public site** (global rule: Astro by default for informational sites). Viable: Astro with the Node adapter can render practitioner profiles from Supabase. The approved architecture names Next.js, mainly for `@supabase/ssr`. This is a visible choice for a later step and is logged in `OPEN_QUESTIONS.md` (Q8), not decided here. It does not affect the private app.
|
||
|
||
Target tree (end state; intermediate states have fewer entries):
|
||
|
||
```text
|
||
apps/
|
||
app/ Vite React private application (current src/, public/, tests/)
|
||
public-web/ Next.js (or Astro SSR) public pages, created at the public-profile step
|
||
worker/ Node worker, created at the agenda/notifications step
|
||
packages/
|
||
domain/ Zod schemas: report document v3, sheet document, species, entitlements
|
||
anatomy/ sheet model helpers, legacy SVG importer, renderer helpers, spine logic
|
||
pdf/ export/import/attachment, render helpers (browser-only rasteriser)
|
||
i18n/ FR/EN dictionaries, useT
|
||
supabase/ client factory, generated Database types, typed RPC wrappers
|
||
ui/ primitives (only when public-web needs them)
|
||
config/ runtime config resolution (env.js / process.env)
|
||
supabase/
|
||
config.toml, migrations/, functions/, seed/, tests/
|
||
docker/
|
||
docs/
|
||
```
|
||
|
||
## 3. Private application (`apps/app`)
|
||
|
||
### 3.1 Route plan
|
||
|
||
Target routes (§21.3) and what replaces what:
|
||
|
||
| Target route | Replaces | Step introduced |
|
||
|---|---|---|
|
||
| `/app` → redirect to `/app/dashboard` | `/` (HomeRoute) | Auth shell |
|
||
| `/app/dashboard` | HomeRoute | Auth shell (empty), filled at Cloud reports |
|
||
| `/app/clients`, `/app/clients/:clientId` | nothing | Clients / Animals |
|
||
| `/app/animals/:animalId` | NewReportRoute (creation entry) | Clients / Animals |
|
||
| `/app/reports/:reportId` | `/editor` | Cloud reports |
|
||
| `/app/anatomy`, `/app/anatomy/:sheetId/editor` | `/svg-editor`, `/editors`, `/pathology-editor.html` | Editor merge |
|
||
| `/app/community` | nothing | Community |
|
||
| `/app/calendar` | nothing | Agenda |
|
||
| `/app/profile/edit`, `/app/settings`, `/app/billing` | nothing | Identity / Billing |
|
||
| `/app/admin/*` | nothing | Administration |
|
||
|
||
Transition rule: legacy routes keep working until the step that replaces them
|
||
lands, then redirect for one release, then disappear. The "local-only" flow
|
||
(no account, sessionStorage draft) is retired at the Cloud reports step; there
|
||
is no customer install base to preserve (CHANGELOG 0.1.0, architecture §23.4).
|
||
|
||
### 3.2 Layers
|
||
|
||
```text
|
||
UI (routes, components)
|
||
↓ calls
|
||
application services (apps/app/src/services/*) one function per use case, no React
|
||
↓ calls
|
||
packages/supabase typed client (RPC, tables, storage)
|
||
↓
|
||
PostgreSQL / RLS / Edge Functions
|
||
```
|
||
|
||
Rule (architecture §21.5): no business rule in a component. Today the click
|
||
chain lives in `EditorRoute.tsx` (`onZoneClick`, lines 290–320, plus four
|
||
handlers). It becomes `services/zoneInteraction.ts`, pure, tested, and the
|
||
route only wires events to it.
|
||
|
||
### 3.3 State
|
||
|
||
Pattern (§21.4): **server data via a query cache, editor session via Zustand**.
|
||
|
||
- Add TanStack Query (`@tanstack/react-query`) for lists and records (clients,
|
||
animals, reports index, sheets, profile). Dependency declared at the Auth
|
||
shell step; stated purpose: cache, invalidation, loading states. Not
|
||
installed in Step 0.
|
||
- `reportStore` keeps the in-memory report document and its actions. Its
|
||
`sessionStorage` subscription becomes one implementation of a persistence
|
||
adapter:
|
||
|
||
```text
|
||
ReportPersistence
|
||
load(reportId): Promise<ReportDocument | null>
|
||
save(reportId, document, meta): Promise<SaveAck> // SaveAck carries server revision
|
||
subscribe(onRemoteChange)
|
||
```
|
||
|
||
Implementations in order of appearance: `sessionStoragePersistence` (today),
|
||
`supabasePersistence` (Cloud reports), `outboxPersistence` (IndexedDB queue
|
||
wrapping the Supabase one, Offline step). The UI shows sync state from the
|
||
adapter and never claims "saved" before the server ack (§Prompt 5).
|
||
- Sheet-version content loaded for a report is read-only in the editor; it is
|
||
cached by the query layer keyed on `sheet_version_id` (immutable, so cache
|
||
forever).
|
||
|
||
### 3.4 Anatomy rendering
|
||
|
||
`AnatomyCanvas` keeps inline SVG + delegated click on `data-anno-id`. The
|
||
renderer takes a canonical view (SVG text from Storage + annotations from the
|
||
document) and emits the `data-anno-*` attributes itself, so `parseSvgBones`
|
||
and the click delegation are unchanged. Detail views open through
|
||
`parent_view_id` / `opened_by_annotation_id` instead of the hard-coded
|
||
`details.head` map.
|
||
|
||
### 3.5 Editors
|
||
|
||
The SVG editor (vanilla DOM in `useEffect`, 1858 lines, zero tests) and the
|
||
pathology editor (static HTML, 1700 lines, zero tests) are not ported. The
|
||
merged Anatomical Sheet editor is written against the canonical document:
|
||
`load document → edit model → render SVG → serialize` (§23.2). The two old
|
||
tools stay reachable and untouched until the merged editor passes their
|
||
functional reference tests (audit 03 §2 and 05 §3.5 enumerate every
|
||
operation), then are deleted in the same step.
|
||
|
||
### 3.6 Runtime configuration
|
||
|
||
`window.__APP_CONFIG__` written by `docker/entrypoint.sh` stays the mechanism.
|
||
New keys: `supabaseUrl`, `supabaseAnonKey`, `publicWebUrl`, later tenant
|
||
branding. The anon key is public; RLS is the boundary. No service-role key
|
||
ever reaches `env.js`.
|
||
|
||
### 3.7 Offline
|
||
|
||
MVP target is network-interruption safety (§26): IndexedDB outbox for unsynced
|
||
report changes, visible sync state, automatic retry, conflict → conflict
|
||
revision chosen by the user. No full offline mirror.
|
||
|
||
## 4. Public site (`apps/public-web`)
|
||
|
||
Scope: landing, practitioner public profiles (`/osteopathe/<slug>`), search,
|
||
sheet discovery pages, later blog and SEO landing pages (§27). Reads only
|
||
public views/RPCs with the anon key; never a broad SELECT on core tables.
|
||
Supabase SSR adapter isolated in one module (the package is beta, §21.2).
|
||
Framework decision (Next.js per architecture vs Astro per global rule) is
|
||
taken at that step, see `OPEN_QUESTIONS.md` Q8.
|
||
|
||
## 5. Worker (`apps/worker`)
|
||
|
||
Node process, same Scaleway host, PostgreSQL-backed job table, no Redis
|
||
(§22.3). Jobs: reminders, appointment expiry (if not `pg_cron`), calendar
|
||
sync, route cache refresh, long imports, archive, sheet garbage collection.
|
||
Introduced when the first job that cannot be a SQL function exists.
|
||
|
||
## 6. Shared packages: contents, dependencies, reason, risk
|
||
|
||
| Package | Contents (from current code) | Depends on | Why extract | Risk |
|
||
|---|---|---|---|---|
|
||
| `packages/domain` | `schema/report.ts` (v2 kept as input, v3 added), `observation.ts`, `findings.ts`, sheet document schema, species, entitlement capability names | zod | Shared by app, public-web (sheet discovery), worker (imports, GC), Edge Functions (validation) | Low. Pure Zod. Must stay free of DOM and Vite (`import.meta.glob` is excluded). |
|
||
| `packages/anatomy` | `svgConvention.ts`, `labels.ts`, generalized `spineZones.ts`, legacy importer (uses `zoneMatch.ts`, `regionFromLabel`), sheet renderer helpers | domain, DOM (`DOMParser`) | Importer runs in a Node script (seed) and in the app (editor import); renderer in app and later server PDF | Medium. DOM dependency: Node needs `linkedom`/`happy-dom` for the importer. Keep DOM-free functions separate from DOM-bound ones inside the package. |
|
||
| `packages/pdf` | `export.ts`, `import.ts`, `attachment.ts`, `render/*`, `fonts.ts` | domain, anatomy, pdf-lib, browser `Image`/`canvas` | Used by app now, by worker later for server-side PDFs | High for the server path: `svgToPng` is browser-only. Extract with a `Rasterizer` interface so a server implementation can be added without touching page layout. |
|
||
| `packages/i18n` | `fr.ts`, `en.ts`, `index.ts`, `useT.ts`, `types.ts` | react (for `useT` only) | public-web and the worker's emails need the same strings | Low. Split `useT` (React) from the dictionaries so the worker does not pull React. |
|
||
| `packages/supabase` | client factories (browser, SSR, service for worker), generated `database.types.ts`, typed RPC wrappers | @supabase/supabase-js | Single place for generated types and auth helpers | Medium. Generated file must be CI-checked against migrations; three client flavours must not share the service key. |
|
||
| `packages/ui` | `components/ui/*`, `styles/tokens.css` | react, tailwind | Only when public-web reuses them | Low, but premature before public-web exists. |
|
||
| `packages/config` | `config/env.ts` resolution (window config vs process.env) | none | app, public-web, worker read the same keys | Low. |
|
||
|
||
Extraction order follows need, not the list: `domain` and `anatomy` first
|
||
(the sheet model is pure code and unblocks the seed), `pdf` and `i18n` next,
|
||
`supabase` with the first DB step, `ui`/`config` with public-web.
|
||
|
||
## 7. Where the current app trusts the frontend (brief §19)
|
||
|
||
Everything, since there is no backend. The items that matter because they
|
||
become multi-tenant:
|
||
|
||
| Trusted today | File | Target boundary |
|
||
|---|---|---|
|
||
| Practitioner identity typed in a form (name, cabinet, contact, SIRET) | `PractitionerForm.tsx`, `practitionerCache.ts` | profile + verification rows; report snapshot copied server-side at creation |
|
||
| Any PDF with a `osteo-report*.json` attachment becomes a report after a shape-only Zod parse | `pdf/import.ts`, `attachment.ts` | import RPC validates ownership, species/sheet existence, quota, then inserts |
|
||
| `speciesId` free string selects the sheet | `AnimalSchema.speciesId`, `NewReportRoute.tsx:20` default `'equine'` | `reports.anatomical_sheet_version_id` FK + `can_use_sheet` policy |
|
||
| SVG sanitization of uploaded files | `SvgEditorRoute.tsx:511-520`, `pathology-editor.html:1127-1136` | server-side sanitizer before an asset becomes readable by others (§15.3) |
|
||
| Catalog edits replace production data by manual file copy | `pathology-editor.html` download → `src/` + `public/` | sheet version publish RPC with schema validation and immutability |
|
||
| Disclaimer acknowledgement | `sessionStorage['osteo:disclaimer-shown']` | legal acceptance recorded with `legal_text_version` when it carries legal weight |
|
||
| Quota / plan | nothing exists | `get_effective_entitlements` + `complete_report` RPC |
|
||
| Locale | `localStorage['osteo:locale']` | fine to keep client-side; mirrored to profile for emails |
|
||
|
||
## 8. Things that must not change in the first structural step
|
||
|
||
- Behaviour of the six routes and the static editor.
|
||
- `pnpm typecheck`, `pnpm test:run` (180 cases), `pnpm lint`, `pnpm build`, Docker build all green with identical semantics.
|
||
- Public asset paths `/species/equine/*` (still fetched by three tools until the sheet seed exists).
|