Contract: N4 voiding instead of deletion, N5 date constraints, N6 write budget per workspace under a lock, N7 effective-privilege wording and residual admin paths, N9 audit metadata limited to ids; M1 as-built notes and isolated-stack results (§8.1). SUPABASE.md §3.3 with the owner procedure to apply M1 on DEV without reset; backend architecture, test strategy, plan and CLAUDE.md lines.
225 lines
14 KiB
Markdown
225 lines
14 KiB
Markdown
# 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
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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.
|
||
|
||
As built from V1-1 (contract `V1-1_OWNERS_ANIMALS.md` §9, BDR-073/074): the
|
||
perimeter is a workspace, not an organization. `private.caller_workspace_ids()`
|
||
(member, active profile, confirmed email; no parameter, `auth.uid()` only;
|
||
EXECUTE for `authenticated`) and `private.writable_workspace_ids()` (the same,
|
||
restricted to a write role; EXECUTE for nobody, called inside definer RPCs)
|
||
replace `is_org_*` and `can_view_client/animal` for V1-1 records. They avoid
|
||
RLS recursion by running as the table owner (`security definer`, owner
|
||
`postgres`, `search_path = ''`) rather than with `row_security = off`. No
|
||
helper or policy has a platform-role branch (D16). Every V1-1 table revokes
|
||
all privileges from `anon` and `service_role` (N7); `postgres` keeps
|
||
`BYPASSRLS` on the Supabase image and the service key stays a GoTrue admin
|
||
credential, residual paths named in the contract §6.3.
|
||
|
||
### 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 |
|
||
| `workspaces`, `workspace_members` (V1-1; cabinets extend them instead of `organizations`) | members, through `caller_workspace_ids()` | none through the API: personal workspace created by trigger; cabinet membership RPCs come with Step 10 |
|
||
| `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).
|