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.
257 lines
20 KiB
Markdown
257 lines
20 KiB
Markdown
# Domain map
|
||
|
||
Status: Step 0 deliverable, 2026-10-08. Derived from
|
||
`faunosteo-business-architecture.md` §2, §4–§20, §24 and confronted with the
|
||
current code (`docs/faunosteo-audit/`). No SQL here: entity names are the
|
||
conceptual tables of the architecture document, listed so that each
|
||
implementation step knows which domain it touches.
|
||
|
||
Conventions used below:
|
||
|
||
- "Entities" = the persisted concepts of the domain (future tables or JSONB documents).
|
||
- "Depends on" = another domain whose rows this domain references (foreign keys or RPC calls).
|
||
- "Reuse" = code in the current repository that survives into this domain (see `REPOSITORY_MIGRATION_MAP.md`).
|
||
- "Server-only" = business rules that must run in PostgreSQL/RLS/RPC, never in the browser (architecture §17, §36; brief §19).
|
||
|
||
## 0. Domain dependency graph
|
||
|
||
```text
|
||
┌────────────┐
|
||
│ Identity │ profiles, roles
|
||
└─────┬──────┘
|
||
┌──────────────┼───────────────────────┬────────────────┐
|
||
▼ ▼ ▼ ▼
|
||
┌───────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ Professional │ │Organizations│ │ Billing & │ │Administration│
|
||
│ Verification │ │ (cabinet) │ │ Entitlements │ │ audit, mod. │
|
||
└───────────────┘ └──────┬──────┘ └──────┬───────┘ └──────────────┘
|
||
│ │ (capabilities)
|
||
┌────────────────┼────────────────────┼─────────────┐
|
||
▼ ▼ ▼ ▼
|
||
┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐
|
||
│ Clients │────▶│ Animals │───────▶│ Reports │ │ Booking │
|
||
└─────────┘ └──────────┘ └─────┬──────┘ └────┬─────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────┐ ┌──────────┐ ┌──────────┐
|
||
│ Anatomical Sheets│ │ Travel │ │ Calendar │
|
||
│ (sheet, version) │ └──────────┘ └──────────┘
|
||
└────────┬─────────┘
|
||
▼
|
||
┌───────────┐
|
||
│ Community │ follow, grants, fork, moderation
|
||
└───────────┘
|
||
|
||
Cross-cutting: Files (Storage metadata), Notifications, Imports,
|
||
Public Profile (SEO), Education (post-MVP).
|
||
```
|
||
|
||
Reading rule: an arrow means "needs rows from". Reports need an Animal and a
|
||
Sheet Version; Community needs Sheets and Identity; Booking needs Clients,
|
||
Animals, Identity and (optionally) Organizations.
|
||
|
||
## 1. Identity
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `profiles` (= `auth.users.id`), `profile_roles` (additive roles: practitioner, student, professor, owner, admin, moderator, support), `platform_invitations` |
|
||
| Depends on | Supabase Auth (email/password, Google, Apple, OTP/magic link, phone verification) |
|
||
| Depended on by | every other domain |
|
||
| Server-only | role grants (admin action, never a browser update), phone/email verification state, invitation acceptance |
|
||
| Reuse | `localeStore` (locale preference becomes `profiles.locale`), `practitionerCache` content shape (name, cabinet, contact, SIRET) seeds the profile form, `ConfigProvider` for runtime Supabase config |
|
||
| Notes | One human = one account; roles are additive (architecture §2.1). Phone verification needs an SMS provider: dependency and cost to confirm (`OPEN_QUESTIONS.md` Q7). |
|
||
|
||
## 2. Professional Verification
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `professional_verifications` (status pending/verified/rejected/expired, SIRET, professional identifier, C2V references), `professional_documents` (RC Pro, C2V proof, other; asset reference, expiry) |
|
||
| Depends on | Identity, Files (document assets), Administration (review by owner/admin, audit log) |
|
||
| Depended on by | Billing & Entitlements (verified status gates professional capabilities), Public Profile (verification badge) |
|
||
| Server-only | status transitions, automatic expiry when a time-bounded document lapses, reviewer identity |
|
||
| Reuse | none; the current app has no identity verification. `PractitionerSchema.siret` is the only overlap. |
|
||
| Notes | Required documents and acceptance criteria are a legal decision before launch (§5). What an unverified account may do is ambiguous (`OPEN_QUESTIONS.md` C6). |
|
||
|
||
## 3. Organizations (Cabinet)
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `organizations`, `organization_members` (owner, manager, secretary, practitioner; `billing_source` seat/personal) |
|
||
| Depends on | Identity, Files (logo), Billing (seats) |
|
||
| Depended on by | Reports (`ownership_scope = organization`), Clients/Animals (grants to an organization), Booking (org-scoped services), Community (grants to an organization), Anatomical Sheets (private sheet shared with an org) |
|
||
| Server-only | membership changes, "secretary cannot self-grant practitioner", one cabinet-paid seat per practitioner at a time |
|
||
| Reuse | none. `Practitioner.cabinet` free text in the report is the only trace of the concept. |
|
||
|
||
## 4. Clients
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `clients` (global person record, optional `auth_user_id`), `client_contacts` (multiple email/phone, normalized, verified), `client_consents` (purpose, legal text version, granted/revoked), `client_access_grants` (grantee user/org, scope, expiry, revocation) |
|
||
| Depends on | Identity (grantees), Organizations (grantees), Administration (audit of consent changes) |
|
||
| Depended on by | Animals, Reports (through Animal), Booking, Notifications (document delivery), Imports |
|
||
| Server-only | candidate matching on normalized contacts without revealing another practitioner's relationship, consent recording with legal text version, grant evaluation |
|
||
| Reuse | `OwnerSchema` (`{ name }`) is the only current owner data; it becomes the identity snapshot inside the report document. |
|
||
| Notes | A *global* client record shared across practitioners is the single most sensitive design choice of the model. See `OPEN_QUESTIONS.md` C4 and Q6. |
|
||
|
||
## 5. Animals
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `animals` (client, species, name, breed, sex, neutered, birth date, identification number, weight, colour, photo asset, notes, deceased fields), `animal_access_grants` |
|
||
| Depends on | Clients, Anatomical Sheets (species reference; species is a first-class list, not a sheet), Files (photo) |
|
||
| Depended on by | Reports, Booking (appointment for an animal), Imports |
|
||
| Server-only | grant evaluation, update rights (owner-controlled vs practitioner-after-consultation, ambiguous in MVP without client accounts: `OPEN_QUESTIONS.md` C5) |
|
||
| Reuse | `AnimalSchema` (`speciesId`, `name`, `breed`, `age`) as the identity snapshot inside the report document; `AnimalForm` as the "new animal" dialog shell. |
|
||
| Notes | Principle 1: an Animal is not an Anatomical Sheet. The animal carries `species_id`; the report chooses a sheet version for that species. |
|
||
|
||
## 6. Anatomical Sheets
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `species` (list: id, labels), `anatomical_sheets` (identity, creator, visibility, status, provenance `based_on_sheet_id`/`based_on_version_id`, `current_version_id`), `anatomical_sheet_versions` (version number, status draft/published/deprecated, `document_schema_version`, `content_jsonb`, assets, publication metadata), sheet assets in Storage (SVG per view) |
|
||
| Canonical document (JSONB) | `schema_version`, `species_id`, `vertebral_config` (ordered regions: code, label FR/EN, count), `views[]` (id, kind main/detail, `parent_view_id`, `opened_by_annotation_id`, `view_box`, `svg_asset_id`), `annotations[]` (stable id, view id, kind point/zone/detail-trigger, category id, names FR/EN, laterality, special, geometry), `categories[]` (id, label, colour), `finding_tree.zones{}` (current `ZoneFindings` shape), `annotation_finding_map[]` (annotation id → finding zone id), `scope_disclaimer`, legacy id map (old `data-anno-id` → new id) kept for migration only |
|
||
| Depends on | Identity (creator), Files (SVG assets), Community (visibility/grants read at use time), Billing (private visibility add-on) |
|
||
| Depended on by | Reports (exact version reference), Community, Animals (species list), Imports (none) |
|
||
| Server-only | version immutability once published, version numbering, garbage collection preconditions (no report, no fork, no grant, no pending process), SVG sanitization before any other user can read the asset, "can use / can fork" evaluation |
|
||
| Reuse | `parseSvgBones` (importer and renderer), `findings.ts` schema (finding tree), `zoneMatch.ts` (importer only), `regionFromLabel` (importer only), `AnatomyCanvas`, `DetailModal`, `VertebraPicker`, `FindingsTreePicker`, the two equine SVGs and the catalog as seed, the tree-edit behaviour of `pathology-editor.html` and the annotation operations of `SvgEditorRoute` as functional references |
|
||
| Notes | Rules 2–8 of the brief (§18) all live here. The current code has no sheet object at all (audit 02 §6): no id, no version, no author, no persisted SVG ↔ catalog link. |
|
||
|
||
## 7. Reports
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `reports` (report number, animal, practitioner, organization nullable, ownership scope, status draft/completed/archived, report date, `anatomical_sheet_version_id`, `current_document`, revision counter, `completed_at`, `free_edit_until`, soft delete), `report_revisions` (document snapshots with reason), `report_access_grants`, `practitioner_report_counters` (row-locked numbering), report PDF artifacts (Files) |
|
||
| Report document (JSONB) | current `Report` v2 shape evolved to v3: observations with zones keyed by `annotationId` + `viewId`, vertebrae with region code, findings with snapshots, free text, severity, comment, conclusion, recommendations, next appointment, identity snapshots (practitioner, animal, client), `localAnnotations[]` (report-only points, see `OPEN_QUESTIONS.md` Q6), locale used for the last PDF |
|
||
| Depends on | Animals (and Clients through them), Identity, Organizations, Anatomical Sheets (exact version), Billing & Entitlements (quota, free edit window), Files (PDF artifacts) |
|
||
| Depended on by | Community (shared report revisions), Booking (appointment ↔ report link, optional), Imports, Notifications (secure sending to the owner) |
|
||
| Server-only | report numbering, completion (quota check, `free_edit_until`), revision checkpoints, "deleted completed reports still count", shared-practitioner revision acceptance, import quota preflight |
|
||
| Reuse | `reportStore` actions (observation CRUD, setters), `ObservationCard`, `ObservationList`, pickers, `ConclusionPanel`, `NextAppointmentPicker`, `pdf/*` pipeline, `Report` v2 schema as adapter input |
|
||
| Notes | Principle 3/4: a report references an exact sheet version. Autosave writes `current_document`; revisions are checkpoints (§9.1). |
|
||
|
||
## 8. Community
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `practitioner_follows`, `sheet_usage_grants` (use / fork, user or org grantee, expiry), `community_reports` (profile/sheet reports, moderation status), public counters (followers, sheet usage) |
|
||
| Depends on | Identity, Anatomical Sheets, Organizations (grantees), Administration (moderation roles) |
|
||
| Depended on by | Reports (which sheets a practitioner may select), Public Profile (follow counts, discovery) |
|
||
| Server-only | "follow grants use of a public sheet", "private sheet needs explicit grant", fork provenance recording, moderation actions by owner/admin/moderator only (support excluded) |
|
||
| Reuse | none directly. |
|
||
| Notes | Mandatory for the commercial MVP (§33). No likes/comments/ratings. |
|
||
|
||
## 9. Booking (Agenda)
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `service_types`, `locations`, `availability_rules`, `availability_exceptions`, `appointments` (status machine requested/confirmed/rejected/cancelled/completed/no_show, request expiry, deposit state, travel minutes, source), `intake_forms`, `intake_questions`, `appointment_intake_answers`, `booking_widget_tokens` |
|
||
| Depends on | Identity, Organizations, Clients, Animals, Travel, Calendar Sync (blocking events), Notifications (reminders, confirmations) |
|
||
| Depended on by | Public Profile (booking entry point), Notifications |
|
||
| Server-only | slot evaluation, pending-request expiry rules (48h / 24h / 1h), one pending request per client per practitioner flow, race-safe slot locking, auto vs manual confirmation, widget token validation |
|
||
| Reuse | `NextAppointmentPicker` as the only link from a report to a future appointment. |
|
||
| Notes | Expiry rules implemented in one database function (§10). |
|
||
|
||
## 10. Travel
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `travel_profiles` (base location, return policy, routing provider, default buffers), `travel_pricing_rules`, route cache |
|
||
| Depends on | Booking (locations, appointments), an external routing provider behind a `RoutingProvider` interface |
|
||
| Depended on by | Booking (availability evaluation) |
|
||
| Server-only | final availability check at booking time (never trust client-computed travel) |
|
||
| Reuse | none. |
|
||
|
||
## 11. Calendar Sync
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `external_calendar_connections` (provider google / apple_ics, encrypted refresh credentials), `external_calendar_events` (blocking state, checksum) |
|
||
| Depends on | Identity, Booking, worker (sync jobs), Notifications (conflict alerts) |
|
||
| Server-only | credential storage and refresh, sync jobs, conflict detection; external event details never exposed to clients |
|
||
| Reuse | none. |
|
||
|
||
## 12. Files (Storage)
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `assets` (bucket, object key, owner scope, resource type/id, mime, size, checksum, sanitization status), buckets `avatars/ logos/ professional-documents/ client-files/ animal-files/ report-files/ anatomical-sheets/ imports/` |
|
||
| Depends on | Identity, and every owning domain for access rules |
|
||
| Depended on by | Verification, Clients, Animals, Reports (PDF artifacts), Anatomical Sheets (SVG), Imports, Public Profile (photos, logos) |
|
||
| Server-only | object key generation (`<resource>/<resource-id>/<asset-id>/<safe-filename>`), signed URL issuance, SVG sanitization and quarantine, `storage.objects` RLS |
|
||
| Reuse | `sanitizeSvg` (10 lines in `SvgEditorRoute` and duplicated in `pathology-editor.html`) as the *client-side* pre-check only; the server sanitizer is new. |
|
||
|
||
## 13. Billing & Entitlements
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `plans`, `subscriptions` (user or organization subscriber, Stripe ids, status, period, cancel at period end), `subscription_seats`, `entitlement_grants` (student, invited, promo, admin, professor), `referrals` (referrer, referred, status, reward months, yearly cap), function `get_effective_entitlements(user_id)` |
|
||
| Depends on | Identity, Organizations, Professional Verification, Stripe (webhooks), Administration (overrides audited) |
|
||
| Depended on by | Reports (quota, `reports.write`, `reports.edit_after_free_window`), Community (`community.publish_sheet`), Booking (`booking.manage`), Public Profile (`profile.public`), Anatomical Sheets (private visibility add-on) |
|
||
| Server-only | everything: effective entitlement computation, free lifetime quota (5 completed reports, deletions and imports count), 5-day free edit window, referral eligibility (verified email + phone, max 5/year), seat exclusivity |
|
||
| Reuse | none. |
|
||
| Notes | The entitlement engine is needed *before* Stripe: the free plan and admin/invited grants must exist when cloud reports ship. The plan therefore splits "entitlement skeleton" (early) from "Stripe billing" (late). |
|
||
|
||
## 14. Imports
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `import_jobs`, `import_files`, `import_raw_records`, `import_mappings`, `import_errors`, `import_unmapped_data` ("Données importées") |
|
||
| Depends on | Identity, Clients, Animals, Reports, Files, Billing (quota preflight), worker (long imports) |
|
||
| Depended on by | none |
|
||
| Server-only | preflight (read-only), quota check before commit, atomic commit (no partial slip of 20 reports on a free account), duplicate candidates never auto-merged |
|
||
| Reuse | `pdf/import.ts` path becomes one adapter ("Faunosteo PDF v2/v3"); `zoneMatch` as a mapping suggestion helper for legacy reports. |
|
||
|
||
## 15. Notifications
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `notification_jobs` (PostgreSQL-backed queue), `email_templates` (FR/EN), delivery log |
|
||
| Depends on | Identity, Booking, Reports, an `EmailProvider` abstraction, worker |
|
||
| Depended on by | Booking (confirmations, reminders), Reports (secure document delivery), Verification (status emails), Billing (invoices) |
|
||
| Server-only | sending, retries, secure link token generation |
|
||
| Reuse | none. |
|
||
|
||
## 16. Administration
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `audit_logs` (actor, action, resource, org, target user, sanitized metadata, correlation id), impersonation sessions (short-lived, audited), moderation queue (Community), legal documents and acceptance versions |
|
||
| Depends on | Identity (owner/admin/moderator/support roles), every domain that emits audit events |
|
||
| Depended on by | Verification (review), Community (moderation), Billing (overrides) |
|
||
| Server-only | all of it; admin MFA mandatory |
|
||
| Reuse | none. |
|
||
|
||
## 17. Public Profile (SEO)
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `public_practitioner_profiles` (slug, public name, bio, photo, logo, locations as permitted, services, prices, intervention zones, species, social links, verification status, published flag), public views/RPCs exposing only approved columns |
|
||
| Depends on | Identity, Verification, Organizations, Booking (services, locations), Files (photo, logo), Community (follow counts) |
|
||
| Depended on by | `apps/public-web`, Booking widget |
|
||
| Server-only | column allow-list in the public view, no clinical/client data reachable anonymously |
|
||
| Reuse | brand components for the platform shell only. |
|
||
|
||
## 18. Education (post-MVP, designed now)
|
||
|
||
| Item | Content |
|
||
|---|---|
|
||
| Entities | `student_professor_links`, `student_access_periods`, student-owned educational reports |
|
||
| Depends on | Identity (student/professor roles), Reports, Billing (student entitlement), Anatomical Sheets |
|
||
| Notes | Must not be built in the MVP, but `profile_roles` and `entitlement_grants` are shaped so it fits later without migration pain. |
|
||
|
||
## 19. Reuse matrix (current code → domain)
|
||
|
||
| Current module | Target domain |
|
||
|---|---|
|
||
| `domain/schema/findings.ts` | Anatomical Sheets (finding tree) |
|
||
| `domain/schema/observation.ts`, `report.ts` | Reports (document v3) |
|
||
| `domain/schema/animal.ts`, `practitioner.ts` | Reports (identity snapshots); Animals / Identity (form shells) |
|
||
| `anatomy/svgConvention.ts` | Anatomical Sheets (importer + renderer) |
|
||
| `lib/zoneMatch.ts`, `lib/spineZones.regionFromLabel` | Anatomical Sheets (importer only), Imports (suggestions) |
|
||
| `lib/spineZones.collect/sync` | Reports (spine interaction) |
|
||
| `state/reportStore.ts` | Reports (editor session + persistence adapter) |
|
||
| `components/observation/*`, `canvas/*` | Reports (editor UI), Anatomical Sheets (editor preview) |
|
||
| `pdf/*` | Reports (PDF artifact), Imports (PDF adapter) |
|
||
| `i18n/*` | cross-cutting |
|
||
| `public/species/equine/*` | Anatomical Sheets (official equine seed v1) |
|
||
| `public/pathology-editor.html`, `SvgEditorRoute.tsx` | Anatomical Sheets (behavioural reference for the merged editor, then deleted) |
|