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.
This commit is contained in:
bchanot committed 2026-10-25 17:12:37 +01:00
1 parent c71fafa3c5
commit ac60b24267
12 files changed
+260 -92

No files matched your search

+55 -42
View File
@@ -3,25 +3,32 @@
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)
│ tables via RLS, RPC (security definer), Storage signed URLs
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)
├─ Auth (GoTrue): email/password, Google, Apple, OTP, phone
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
├─ Edge Functions (Deno): public endpoints, webhooks, signed-URL issuance
└─ Realtime (optional): report sync state
Worker (apps/worker, service key, same host)
└─ jobs table in PostgreSQL, no Redis
public-web (anon key, SSR)
└─ 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).
@@ -33,8 +40,8 @@ key or third-party refresh token (§17.1).
| 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 | |
| Roles | `profile_roles` table, never JWT custom claims as the only source (claims can lag) | helpers read the table |
| 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.
@@ -51,7 +58,7 @@ 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_jsonb`) carry their own `schema_version` and are validated by the matching Zod schema at the application boundary and by a CHECK on `schema_version` in SQL. SQL does not re-implement Zod.
- 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
@@ -102,40 +109,42 @@ EXECUTE on those functions and nothing else.
## 5. Storage
Buckets, all private: `avatars`, `logos`, `professional-documents`,
`client-files`, `animal-files`, `report-files`, `anatomical-sheets`, `imports`.
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 key: `<resource-type>/<resource-id>/<asset-id>/<safe-filename>`. The
`assets` table is authoritative; `storage.objects` policies call the owning
helper (`can_view_report` for `report-files/...`). Reads go through signed
URLs issued by an RPC/Edge Function after the same check.
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.
SVG pipeline (§15.3): upload lands in a quarantine prefix with
`assets.sanitization_status = pending`; a server sanitizer (Edge Function or
worker) rewrites the file (strip `<script>`, `<foreignObject>`, `on*`,
`javascript:`/external hrefs, `<use>` to external documents, CSS `url()`),
stores the clean bytes under the final key and sets `status = clean`. Policies
only allow reading `clean` assets to anyone other than the uploader. The
current 10-line client sanitizer stays as a pre-check in the editor, not as
the boundary.
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. Edge Functions vs PostgreSQL functions vs worker
## 6. PostgreSQL functions vs Rust worker vs Rust HTTP services
Decision rule for each server-side behaviour:
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 |
| Edge Function | Needs HTTP from outside or secrets: Stripe webhooks, public widget endpoints, signed-URL issuance, calendar OAuth callbacks, email send trigger, SVG sanitization (small files), import preflight (small files) |
| Worker | Long or scheduled: reminders, expiry sweeps (unless `pg_cron`), calendar sync, route cache, long imports, archive, GC sweeps, server PDF (later) |
| 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) |
Self-hosted note: Edge Functions on a self-hosted stack run in the
`edge-runtime` container and must be deployed by hand. The first steps lean
on PostgreSQL functions, which the CLI migrates and tests natively. See
`OPEN_QUESTIONS.md` Q2 on VPS sizing.
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
@@ -146,9 +155,12 @@ on PostgreSQL functions, which the CLI migrates and tests natively. See
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/`): species list, plans, the official equine sheet
v1 produced by the importer from the two SVGs and the catalog. Seeds are
idempotent and versioned like migrations.
- 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).
@@ -167,9 +179,10 @@ Representative cross-tenant cases are a release gate (§30).
## 9. Generated types
`supabase gen types typescript --local > packages/supabase/src/database.types.ts`
after every migration. CI regenerates and fails on diff. Zod schemas in
`packages/domain` remain the contract for JSONB documents; 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)
@@ -182,7 +195,7 @@ cover columns and RPC signatures.
6. Entitlement computation and Stripe state.
7. Referral eligibility and caps.
8. Client candidate matching and sharing consent flows.
9. SVG sanitization and signed URL issuance.
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.