Files
faunosteo/docs/development/DOMAIN_MAP.md
T
bchanot a6346105f1 docs(docs): V1-1 contract approved, technical design for review
Owner ratified the V1-1 business decisions. The contract now records them
as approved, adds the nomenclature, the proposed SQL schema, RLS, RPCs,
technical limits, journeys and test plan, and lists the choices left for
the owner. OPEN_QUESTIONS, plan, DOMAIN_MAP, README and CLAUDE.md follow.
2026-10-25 19:15:35 +01:00

265 lines
21 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.
Revised 2026-10-25 (P0): platform roles (BDR-026), sheet document fields
(BDR-031), Storage as built (`STORAGE.md`). The "Reuse" rows and §19 describe
the code of 2026-10-08: the TypeScript modules they name have since moved into
`crates/core` or been deleted (Steps 5 to 8, R2 to R5); `CLAUDE.md` holds the
current map. Clients and Animals (§4, §5) are being reframed by the V1-1
contract (`V1-1_OWNERS_ANIMALS.md`): workspaces, no global client record,
client-animal links with roles; business decisions ratified by the owner on
2026-10-25 (BDR-073); where this map differs, the contract governs V1-1.
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` (enum `platform_role`: owner, admin, moderator, support; BDR-026), `platform_invitations` (not built). Professional statuses (practitioner, student, professor) are outcomes of Professional Verification, cabinet roles live in the cabinet membership: neither is a platform role. |
| 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 by finding zone, `finding_zone_id` inline on each annotation (no separate map, BDR-031), `scope_disclaimer`; legacy id mapping kept in the seed's generated files and the report migration map. Exact shape: `ANATOMICAL_SHEET_MODEL.md` |
| 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 reading by the core 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); the locale stays out of the report (BDR-014), the PDF envelope records it |
| 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` (status, owner, server-built keys, lease; `STORAGE.md`), buckets `avatars` (policies), `logos`, `professional-documents`, `client-files`, `animal-files`, `report-files`, `imports` (closed), `anatomical-sheet-assets` (sheet drawings) |
| 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 from uuids, quarantine and decoding in the Rust worker's sandboxed child, `storage.objects` RLS through `assets`; owner-only files read under RLS with no signed URL (BDR-048) |
| 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 and Professional Verification (student/professor statuses, not platform roles: BDR-026), Reports, Billing (student entitlement), Anatomical Sheets |
| Notes | Must not be built in the MVP, but verification statuses and `entitlement_grants` are shaped so it fits later without migration pain. No plan step owns education yet. |
## 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) |