Files
faunosteo/docs/development/BACKEND_ARCHITECTURE.md
T
bchanot ac60b24267 docs(docs): realign active docs on develop for P0
Roadmap section and step statuses in the plan, D-R9 Rust services in
place of Edge Functions and a Node worker, platform roles per BDR-026,
equine sheet draft-only, curation-only authoring until Step 17,
OPEN_QUESTIONS statuses and conflict resolutions, dated snapshot
notices on the Step 0 documents.
2026-10-25 17:12:37 +01:00

13 KiB
Raw Blame History

Backend architecture (Supabase strategy)

Status: Step 0 deliverable, 2026-10-08. Conceptual only. No migration, table, policy or function is created by this document. Table and function names follow faunosteo-business-architecture.md §4–§20. Revised 2026-10-25 (P0): Edge Functions retired (D-R9, BDR-045), worker = crates/worker in Rust, data contracts in crates/core (R2), bucket list and signed-URL rule as built at Step 8 (STORAGE.md). Hosting stays open (OPEN_QUESTIONS.md Q2).

1. Components and what runs where

Browser (apps/app, anon key + user JWT, Rust core as WebAssembly)
   │  tables via RLS, RPC (security definer), Storage under storage.objects policies
   ▼
Supabase (self-hosted on Scaleway at launch, §31; hosting open, Q2)
   ├─ Auth (GoTrue): email/password, OAuth providers (Google, Apple), OTP, phone; keeps the OAuth flows (D-R9)
   ├─ PostgreSQL: schemas public / private / audit, RLS, functions, pg_cron
   └─ Storage: private buckets, storage.objects policies evaluated on public.assets
Rust worker (crates/worker, container faunosteo_worker, service key, same host)
   └─ jobs claimed from PostgreSQL through RPCs (lease token), no Redis; decode child sandboxed
Rust HTTP services (same image, other subcommands, own secrets; from the first inbound need)
   └─ webhooks (Stripe), OAuth callbacks of external calendars, public endpoints that SQL cannot serve
public-web (Astro, D-R8; anon key)
   └─ public views / RPCs only

Edge Functions are not used (D-R9): limits on the self-hosted edge runtime, hand deployment, and one Rust runtime for every server process.

The browser never holds a service-role key, admin credential, storage master key or third-party refresh token (§17.1).

2. Auth

Need Mechanism Note
Email/password, magic link/OTP GoTrue built-in strong password policy configured server-side
Google, Apple GoTrue OAuth providers Apple requires a paid developer account and a services id: dependency to confirm
Phone verification GoTrue phone OTP needs an SMS provider (Twilio, MessageBird, Vonage) cost and EU processing to confirm; see OPEN_QUESTIONS.md Q7
Email verification GoTrue, mandatory before professional features
MFA GoTrue TOTP; mandatory for owner/admin/moderator/support roles, enforced by RLS helper has_mfa() on admin tables TOTP enabled server-side; has_mfa(), enrolment and enforcement not built (IDENTITY.md §4, TODO RR-3)
Roles profile_roles table with the platform_role enum (owner, admin, moderator, support: BDR-026), never JWT custom claims as the only source (claims can lag) helpers read the table; professional statuses (practitioner, student, professor) come from verification, cabinet roles from membership, never from this enum
Impersonation dedicated RPC issuing a short-lived scoped session, audited, banner in UI (§17.5) after MVP core

profiles.id = auth.users.id, created by a trigger on auth.users insert.

3. PostgreSQL layout

Schema Content Exposure
public tables exposed to PostgREST, all with RLS enabled, separate SELECT/INSERT/UPDATE/DELETE policies browser, public-web, worker
private security-definer helper functions, internal tables (counters, job queue, route cache), triggers not exposed to PostgREST
audit audit_logs, append-only, insert via private.log_event() read by admins through a view

Conventions fixed now so every step follows them:

  • UUID primary keys (gen_random_uuid()), created_at / updated_at with a shared trigger, soft delete deleted_at where the architecture names it.
  • Enums as PostgreSQL enum types when the value set is closed by the business (report status, appointment status), text + CHECK when the set is expected to grow (document types).
  • JSONB documents (reports.current_document, anatomical_sheet_versions.content) carry their own schema_version and are validated by the Rust core's contracts (crates/core/src/domain, since R2) at the application boundary and by a CHECK on schema_version in SQL. SQL re-checks only what publication needs (private.sheet_document_issues, BDR-032), with the same rule codes as the core.
  • Every table exposed to the browser: RLS enabled, no USING (true) policy for authenticated, no anonymous policy on core tables (§17.4).

4. RLS strategy

4.1 Helpers

Security-definer functions in private, STABLE, search_path pinned, SET row_security = off inside where they read tables that have policies referencing them (prevents recursion), one index per access path they use:

private.is_platform_owner(uid)        private.is_platform_admin(uid)
private.is_platform_moderator(uid)    private.is_support(uid)
private.is_org_member(uid, org)       private.is_org_manager(uid, org)
private.is_org_practitioner(uid, org)
private.can_view_client(uid, client)  private.can_view_animal(uid, animal)
private.can_view_report(uid, report)  private.can_edit_report(uid, report)
private.can_use_sheet(uid, sheet)     private.can_fork_sheet(uid, sheet)
private.has_active_entitlement(uid, capability text)

Each helper ships with pgTAP tests in the same migration step: positive case, negative case, expired grant, revoked grant, wrong organization.

4.2 Policy rules per domain (summary of §17.3)

Table family SELECT INSERT/UPDATE/DELETE
profiles own row; admins via view own row; roles only through RPC
organizations, organization_members members managers/owners through RPC (add_member, remove_member, set_role) so that "secretary cannot self-grant practitioner" is one place
clients, client_contacts, client_consents can_view_client create by the practitioner who starts the relationship; core identity edits restricted (open question Q6)
animals can_view_animal practitioner with an active relationship or grant
reports can_view_report can_edit_report for drafts; completion and numbering only via RPC
report_revisions same as parent report insert via RPC/trigger only
anatomical_sheets public metadata through a view; full row for creator, grantee, or follower of a public sheet creator only; publish via RPC
anatomical_sheet_versions can_use_sheet on the parent insert draft by creator; published rows immutable (trigger raises on UPDATE of content_jsonb when status = published)
practitioner_follows, sheet_usage_grants involved parties own follows; grants by sheet creator or org manager
appointments and agenda tables owner scope; public availability through RPC only booking through RPC with row locks
plans, subscriptions, entitlement_grants own / org manager Stripe webhook (service) and admin RPC only
audit.audit_logs admins append-only via private.log_event
storage.objects per bucket policy calling the owning domain's helper upload paths validated against assets rows

4.3 Public endpoints

Public profile, sheet discovery, availability and booking are security-definer RPCs or narrow views returning approved columns (§17.4). The anon role gets EXECUTE on those functions and nothing else.

5. Storage

Buckets, all private, as built (STORAGE.md): avatars (the only one with policies), logos, professional-documents, client-files, animal-files, report-files, imports (closed until their step writes the rules), and anatomical-sheet-assets (sheet drawings, its own policy).

Object keys are built by the server from uuids (profiles/<owner>/<id>/avatar.webp, quarantine/<owner>/<id>/upload). The assets table is authoritative; storage.objects policies compare whole keys through assets. Owner-only files are downloaded under the SELECT policy with no signed URL (BDR-048); a shared kind may use a short-lived signed URL issued by the Storage API after the same policy. There is no issue_signed_url RPC.

Untrusted uploads (§15.3) land under a quarantine key; the Rust worker's sandboxed child decodes them and writes the clean object; a quarantine object is never readable by an API role. User SVG uploads arrive with Step 13 and go through the Rust core's one SVG reader (prescan caps, allowlist, reference graph), never a browser sanitiser as the boundary.

Archive (§15.4, §16): S3-compatible cold storage with lifecycle rules, no Object Lock by default. Out of MVP core; designed at the data-lifecycle step.

6. PostgreSQL functions vs Rust worker vs Rust HTTP services

Decision rule for each server-side behaviour (D-R9 replaced the Edge Functions row):

Put it in When
PostgreSQL function / trigger (RPC) Needs transactional guarantees with the data: report numbering, completion + quota, booking slot lock, grant evaluation, version publication, GC preconditions
Rust HTTP service (crates/worker image, serve subcommand behind the reverse proxy) Needs inbound HTTP from outside or third-party secrets: Stripe webhooks, public widget endpoints SQL cannot serve, external calendar OAuth callbacks; each service holds only its own secrets
Rust worker (crates/worker, job loop) Long, scheduled or untrusted-bytes work: file decoding (avatar since Step 8), reminders and email sending, expiry sweeps (unless pg_cron), calendar sync, route cache, long imports, archive, GC sweeps, server PDF (later)

Supabase Auth keeps the OAuth sign-in flows it already handles. Shared rules come from crates/core; the worker and the HTTP services are distinct processes with their own least privilege. See OPEN_QUESTIONS.md Q2 on VPS sizing.

7. Migrations

  • Supabase CLI, supabase/migrations/<timestamp>_<name>.sql, forward-only, one or more per implementation step, reviewed in the step's PR.
  • A migration never edits an applied migration; corrections are new migrations.
  • Each migration that adds a table also adds: RLS enable, policies, indexes listed in §32 of the architecture, pgTAP tests, and regenerated types.
  • supabase db reset must succeed from zero on CI, then supabase test db, then the app test suite (§36).
  • Seed data (supabase/seed/): the official equine sheet as a DRAFT, generated by the Rust pipeline (pnpm import:equine) from the legacy sources and the curation changeset; it is published only by a platform admin after business review (BDR-034, BDR-037). Reference lists (species, later plans) are written by migrations. Seeds are idempotent and versioned like migrations.
  • Production changes follow expand/contract when a column is renamed or dropped (the deprecation-and-migration skill applies).

8. SQL tests

pgTAP under supabase/tests/, run by supabase test db:

  • helper function unit tests (one file per helper);
  • per-table RLS tests: as user A, as user B, as org member, as anon, as service; each verifies both the allowed rows and the denied rows;
  • transactional rules: numbering under concurrency (two sessions), booking double-request, completion beyond quota, publish-then-update raises;
  • immutability and GC preconditions for sheet versions.

Representative cross-tenant cases are a release gate (§30).

9. Generated types

pnpm db:types regenerates packages/supabase/src/database.types.ts after every migration; pnpm db:types:check diffs it (no CI runs on the forge, BDR-047). The Rust contracts of crates/core/src/domain, exported to TypeScript by ts-rs, are the contract for JSONB documents; generated types cover columns and RPC signatures.

10. What must stay server-side (brief §19, architecture principles 6–13)

  1. Authorization: every read/write of client, animal, report, sheet, grant.
  2. Report numbering, completion, free-plan quota, 5-day free edit window.
  3. Sheet version immutability, publication, deprecation, garbage collection.
  4. Explicit annotation → finding zone mapping validation on publish (no fuzzy at runtime).
  5. Booking slot evaluation, pending-request limits, expiry, race protection.
  6. Entitlement computation and Stripe state.
  7. Referral eligibility and caps.
  8. Client candidate matching and sharing consent flows.
  9. Untrusted file decoding (worker child), SVG reading by the core on every product drawing, Storage access through policies.
  10. Import preflight, quota check and atomic commit.
  11. Audit logging, impersonation, moderation.
  12. Archive and deletion workflows.

11. Observability and operations (minimum for MVP)

  • Structured logs without clinical data or secrets; request correlation id propagated to audit_logs.
  • Daily DB backup + monthly retained copy; restore rehearsed before the first paying cohort (§31, §38).
  • Dependency audit (pnpm audit) and secret scan (gitleaks hook already in .githooks) in CI.
  • Security headers at the reverse proxy and in nginx (hardening step).