Contract §11.6: D13 final behaviour of the native modal dialog, D14 as built against the isolated stack, the three mobile navigation sources and their consequences for Clients and Animaux. BROWSER_TESTS.md: suites, prerequisites, guarantees, failures, limits. TEST_STRATEGY, SUPABASE §5.1, FRONTEND snapshot note, CLAUDE.md.
13 KiB
Frontend architecture (target)
Status: Step 0 deliverable, 2026-10-08. Proposal only; the repository is not
transformed by this document.
Snapshot notice (2026-10-25, P0): this text describes the app of 2026-10-08
and its planned target. Since then: auth and the /app shell exist (Step 7,
IDENTITY.md), the worker is the Rust crates/worker (not a Node apps/worker),
Edge Functions are retired (D-R9), the packages domain, anatomy, pdf and
pdf-lib were replaced by crates/core and deleted (R4.8, R5.7), the legacy
editors and public/species were deleted at Step 5, no TanStack Query
(BDR-041), the public site framework is Astro (D-R8). CLAUDE.md (folder map,
architecture) is the current description. V1-1.3 (2026-10-25): every modal
(Dialog, the mobile drawer) is built on components/ui/ModalDialog.tsx, the
native <dialog> in modal mode (behaviour in V1-1_OWNERS_ANIMALS.md §11.6),
and the real-browser suites live in apps/app/e2e (BROWSER_TESTS.md).
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-webbeside it. Rejected: path aliases (@/*), Docker build context, tsconfig includes and Vitest config would all special-case the root app;pnpm-workspace.yamlalready exists at the root (it only holdsallowBuildstoday), 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 inOPEN_QUESTIONS.md(Q8), not decided here. It does not affect the private app.
Target tree (end state; intermediate states have fewer entries):
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
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. reportStorekeeps the in-memory report document and its actions. ItssessionStoragesubscription becomes one implementation of a persistence adapter:
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).