Files
faunosteo/docs/development/DOMAIN_MAP.md
T
bchanot b0cce2cd8c docs(docs): add SaaS implementation plan and architecture docs (step 0)
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.
2026-10-08 21:41:39 +02:00

257 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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) |