# 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 `` 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`). V1-1.5 (2026-10-26): the first record screens, the clients (`V1-1_OWNERS_ANIMALS.md` §11.7): data access only through `packages/supabase` (closed `RecordFailure` kinds), page-local state in hooks under `apps/app/src/clients/`, the personal workspace in `authStore`, the routes behind `RequireWorkspace`, unsaved changes guarded by `useLeaveGuard` and `AppLayout`. No data cache library: each page reads what it shows. V1-1.6 (2026-10-26): the animal screens and the relations (§11.8): hooks under `apps/app/src/animals/` and `apps/app/src/relations/`, components under `components/{animals,relations}/`; one `RequireWorkspace` above the client and animal routes, which also holds the species labels (read once per workspace, dropped with it); no new business rule in TypeScript (the M3 RPCs decide, the schemas are D-R7 form checks, age and grouping are display). ## 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 save(reportId, document, meta): Promise // 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/`), 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).