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.
20 KiB
20 KiB
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
┌────────────┐
│ 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) |