Files
faunosteo/docs/development/FRONTEND_ARCHITECTURE.md
T
bchanot e215e9b2cb docs(docs): V1-1.6 as built, D11 drawer only, closure inventory, DEV steps
Contract §11.8 and §15; D11 and U3 decided, D12 open; SUPABASE.md §3.3 gains
the rehearsed restore check and the owner's browser acceptance on DEV; browser,
test and frontend docs, design README, CLAUDE.md map.
2026-10-26 17:24:19 +01:00

14 KiB
Raw Blame History

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). 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):

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.
  • reportStore keeps the in-memory report document and its actions. Its sessionStorage subscription 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).