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:
1 parent
c71fafa3c5
commit
ac60b24267
12 files changed
+260
-92
No files matched your search
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user