Files
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

21 KiB
Raw Permalink Blame History

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

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