docs(docs): SUPABASE.md runbook + CLAUDE/README/DEPLOY/WORKSPACE updated for the Supabase foundation
This commit is contained in:
1 parent
5511a2158a
commit
1dd45a3109
7 files changed
+267
-26
No files matched your search
@@ -51,15 +51,15 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
|
|||||||
- [x] Step 2 — monorepo workspace: apps/app via git mv (144 files), root scripts, Node 24 + pnpm 10.13.1 pins, Dockerfile node:24 + filtered build, CI .gitea/workflows/ci.yml, WORKSPACE.md; 271/271, typecheck, lint, build green from root (2026-10-08, branch feature/step-02-monorepo-workspace, uncommitted, awaiting validation)
|
- [x] Step 2 — monorepo workspace: apps/app via git mv (144 files), root scripts, Node 24 + pnpm 10.13.1 pins, Dockerfile node:24 + filtered build, CI .gitea/workflows/ci.yml, WORKSPACE.md; 271/271, typecheck, lint, build green from root (2026-10-08, branch feature/step-02-monorepo-workspace, uncommitted, awaiting validation)
|
||||||
- [ ] Step 3 — Supabase foundation (2026-10-08, branch feature/step-03-supabase-foundation)
|
- [ ] Step 3 — Supabase foundation (2026-10-08, branch feature/step-03-supabase-foundation)
|
||||||
- [x] 3.0 context: plan Step 3, BACKEND_ARCHITECTURE §2-§9, business §4.1/§17/§29; Docker socket denied to user → PGlite harness as executable proof, pgTAP kept for `supabase test db`
|
- [x] 3.0 context: plan Step 3, BACKEND_ARCHITECTURE §2-§9, business §4.1/§17/§29; Docker socket denied to user → PGlite harness as executable proof, pgTAP kept for `supabase test db`
|
||||||
- [ ] 3.1 supabase/config.toml (CLI pinned as root devDependency) + `supabase/seed.sql` (local users only)
|
- [x] 3.1 supabase/config.toml (CLI pinned as root devDependency) + `supabase/seed.sql` (local users only)
|
||||||
- [ ] 3.2 migration 0001 foundation: schemas private/audit, set_updated_at, audit.audit_logs append-only, private.log_event
|
- [x] 3.2 migration 0001 foundation: schemas private/audit, set_updated_at, audit.audit_logs append-only, private.log_event
|
||||||
- [ ] 3.3 migration 0002 profiles: table, auth.users trigger, protected columns trigger, RLS own row (+ staff read), grants
|
- [x] 3.3 migration 0002 profiles: table, auth.users trigger, protected columns trigger, RLS own row (+ staff read), grants
|
||||||
- [ ] 3.4 migration 0003 platform roles: enum platform_role (owner/admin/moderator/support), profile_roles, private.is_platform_* helpers, grant/revoke RPC with audit, RLS
|
- [x] 3.4 migration 0003 platform roles: enum platform_role (owner/admin/moderator/support), profile_roles, private.is_platform_* helpers, grant/revoke RPC with audit, RLS
|
||||||
- [ ] 3.5 pgTAP tests supabase/tests/*.sql (schema, profiles RLS allow+deny, roles allow+deny, audit append-only)
|
- [x] 3.5 pgTAP tests supabase/tests/*.sql (schema, profiles RLS allow+deny, roles allow+deny, audit append-only)
|
||||||
- [ ] 3.6 packages/supabase: PGlite harness (auth shim + migrations) + vitest RLS suite (allow+deny), database.types.ts (generator format) + schema↔types consistency test, browser client factory
|
- [x] 3.6 packages/supabase: PGlite harness (auth shim + migrations) + vitest RLS suite (allow+deny), database.types.ts (generator format) + schema↔types consistency test, browser client factory
|
||||||
- [ ] 3.7 app integration: env.ts supabaseUrl/anonKey, lib/supabase.ts lazy client (null when unconfigured), entrypoint.sh + .env.example + compose; no UI change; tests
|
- [x] 3.7 app integration: env.ts supabaseUrl/anonKey, lib/supabase.ts lazy client (null when unconfigured), entrypoint.sh + .env.example + compose; no UI change; tests
|
||||||
- [ ] 3.8 CI: supabase job (start, db reset, test db, gen types diff); check job runs PGlite suite via pnpm -r
|
- [x] 3.8 CI: supabase job (start, db reset, test db, gen types diff); check job runs PGlite suite via pnpm -r
|
||||||
- [ ] 3.9 docs: docs/development/SUPABASE.md (start/reset/test/types/bootstrap owner), CLAUDE.md folder map + scopes, README pointer
|
- [x] 3.9 docs: docs/development/SUPABASE.md (start/reset/test/types/bootstrap owner), CLAUDE.md folder map + scopes, README pointer
|
||||||
- [ ] 3.10 verify: typecheck, test:run (271 + new), lint, build; registries + journal; report
|
- [ ] 3.10 verify: typecheck, test:run (271 + new), lint, build; registries + journal; report
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -11,7 +11,9 @@ Single-praticien French web app for veterinary osteopathy bilans on animal anato
|
|||||||
Practitioner clicks anatomical zones, builds observations with pathologies/severity,
|
Practitioner clicks anatomical zones, builds observations with pathologies/severity,
|
||||||
writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native
|
writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native
|
||||||
attachment so importing it restores the session for a follow-up.
|
attachment so importing it restores the session for a follow-up.
|
||||||
Static SPA, no backend, no auth. Deployed via Docker + nginx on Scaleway VPS.
|
SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase
|
||||||
|
(PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and
|
||||||
|
audit log exist; the UI does not use the client yet (local-only flows unchanged).
|
||||||
MVP species: equine only. Open-source MIT.
|
MVP species: equine only. Open-source MIT.
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -32,15 +34,18 @@ MVP species: equine only. Open-source MIT.
|
|||||||
| SVG raster | native Image/canvas (no dependency) | — |
|
| SVG raster | native Image/canvas (no dependency) | — |
|
||||||
| Animation | motion | 11 |
|
| Animation | motion | 11 |
|
||||||
| Tests | vitest + happy-dom + @testing-library/react | 3.x |
|
| Tests | vitest + happy-dom + @testing-library/react | 3.x |
|
||||||
|
| Backend | Supabase (PostgreSQL 17, GoTrue, PostgREST) — CLI pinned as root devDependency | CLI 2.120 |
|
||||||
|
| DB client | @supabase/supabase-js (packages/supabase) | 2.x |
|
||||||
|
| SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 |
|
||||||
| Deploy | Docker multi-stage → nginx:alpine | — |
|
| Deploy | Docker multi-stage → nginx:alpine | — |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Build commands
|
## Build commands
|
||||||
|
|
||||||
pnpm workspace: `apps/app` = the private application, `packages/` empty for
|
pnpm workspace: `apps/app` = the private application, `packages/supabase` =
|
||||||
now (see `docs/development/WORKSPACE.md`). Every command below runs from the
|
Supabase access layer (see `docs/development/WORKSPACE.md`). Every command
|
||||||
repository root and delegates to the packages.
|
below runs from the repository root and delegates to the packages.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Development
|
# Development
|
||||||
@@ -66,6 +71,13 @@ pnpm lint
|
|||||||
|
|
||||||
# Format
|
# Format
|
||||||
pnpm format
|
pnpm format
|
||||||
|
|
||||||
|
# Supabase local stack (Docker) — docs/development/SUPABASE.md
|
||||||
|
pnpm db:start # start stack, apply migrations + seed
|
||||||
|
pnpm db:reset # replay from zero
|
||||||
|
pnpm db:test # pgTAP on the real stack
|
||||||
|
pnpm db:types # regenerate packages/supabase/src/database.types.ts
|
||||||
|
pnpm db:types:check # CI diff
|
||||||
```
|
```
|
||||||
|
|
||||||
## Docker commands
|
## Docker commands
|
||||||
@@ -96,6 +108,8 @@ pnpm test # vitest watch — dev loop
|
|||||||
Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in
|
Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in
|
||||||
`apps/app/tests/fixtures/`. Setup: `apps/app/tests/setup.ts` imports
|
`apps/app/tests/fixtures/`. Setup: `apps/app/tests/setup.ts` imports
|
||||||
@testing-library/jest-dom. Characterisation suite: files prefixed `char.`.
|
@testing-library/jest-dom. Characterisation suite: files prefixed `char.`.
|
||||||
|
SQL: `supabase/tests/*.sql` (pgTAP) run by `packages/supabase/tests/db/pgtap.test.ts`
|
||||||
|
on PGlite (part of `pnpm test:run`) and by `pnpm db:test` on the real stack.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -159,7 +173,7 @@ faunosteo/
|
|||||||
│ ├─ pdf/
|
│ ├─ pdf/
|
||||||
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
|
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
|
||||||
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.ts
|
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.ts
|
||||||
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones}.ts
|
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones,supabase}.ts ← supabase.ts: getSupabaseClient() | null
|
||||||
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
|
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
|
||||||
│ └─ main.tsx
|
│ └─ main.tsx
|
||||||
├─ tests/
|
├─ tests/
|
||||||
@@ -178,7 +192,14 @@ faunosteo/
|
|||||||
├─ eslint.config.js, index.html, package.json (@faunosteo/app)
|
├─ eslint.config.js, index.html, package.json (@faunosteo/app)
|
||||||
├─ tsconfig*.json, vite.config.ts, vitest.config.ts
|
├─ tsconfig*.json, vite.config.ts, vitest.config.ts
|
||||||
│ (end of apps/app)
|
│ (end of apps/app)
|
||||||
├─ packages/README.md ← future shared packages (none yet)
|
├─ packages/supabase/ ← @faunosteo/supabase
|
||||||
|
│ ├─ src/{index,client,database.types}.ts ← typed browser client + generated types
|
||||||
|
│ └─ tests/{client.test.ts,db/} ← PGlite harness, shim, pgTAP runner, schema↔types test
|
||||||
|
├─ supabase/
|
||||||
|
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
|
||||||
|
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles
|
||||||
|
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
|
||||||
|
├─ packages/README.md ← shared packages index
|
||||||
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
|
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
|
||||||
├─ .claude/{tasks/TODO.md,memory/,audits/}
|
├─ .claude/{tasks/TODO.md,memory/,audits/}
|
||||||
├─ Dockerfile, docker-compose.yml, docker/
|
├─ Dockerfile, docker-compose.yml, docker/
|
||||||
@@ -224,6 +245,14 @@ Runtime config
|
|||||||
→ index.html loads env.js before bundle
|
→ index.html loads env.js before bundle
|
||||||
→ src/config/env.ts reads window.__APP_CONFIG__ → VITE_APP_* → defaults
|
→ src/config/env.ts reads window.__APP_CONFIG__ → VITE_APP_* → defaults
|
||||||
→ ConfigProvider exposes via React context
|
→ ConfigProvider exposes via React context
|
||||||
|
→ appConfig.supabase (url + anon key) or null → lib/supabase.ts lazy client
|
||||||
|
|
||||||
|
Database (Supabase)
|
||||||
|
→ schemas: public (exposed, RLS on every table) / private (helpers, triggers) / audit (append-only)
|
||||||
|
→ auth.users insert → private.handle_new_auth_user() → public.profiles row
|
||||||
|
→ platform roles: public.profile_roles written only by grant_platform_role / revoke_platform_role
|
||||||
|
(security definer, actor checked via private.is_platform_*; every call logged by private.log_event)
|
||||||
|
→ tests: supabase/tests/*.sql (pgTAP) via PGlite in CI check job and `supabase test db`
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -278,6 +307,20 @@ Runtime config
|
|||||||
- boneIds: [] = all zones; speciesIds: [] = all species
|
- boneIds: [] = all zones; speciesIds: [] = all species
|
||||||
- Source types: manual | journal | database | web
|
- Source types: manual | journal | database | web
|
||||||
|
|
||||||
|
### Database (Supabase)
|
||||||
|
- Platform roles (`platform_role`: owner/admin/moderator/support) are NOT professional
|
||||||
|
statuses (practitioner/student/professor come from verification, cabinet roles from
|
||||||
|
organization_members). Never add a professional status to `platform_role`.
|
||||||
|
- Every `public` table: RLS enabled, `revoke all` from API roles then exact grants,
|
||||||
|
separate policies per command, no `using (true)` for anon/authenticated (test-enforced).
|
||||||
|
- Writes that change privileges or sensitive state go through a security-definer RPC
|
||||||
|
that checks `auth.uid()` and calls `private.log_event()`. Never a direct table policy.
|
||||||
|
- Helpers in `private` are `security definer`, `set search_path = ''`, EXECUTE revoked
|
||||||
|
from public and granted only to the roles that evaluate them.
|
||||||
|
- A migration is never edited once applied. Each migration ships its pgTAP file with
|
||||||
|
allowed AND denied cases, and a regenerated `database.types.ts`.
|
||||||
|
- The browser holds the anon key only. `service_role` never appears in env.js, .env.example or code.
|
||||||
|
|
||||||
### Component stubs
|
### Component stubs
|
||||||
- Scaffold stubs render <div>ComponentName placeholder</div>
|
- Scaffold stubs render <div>ComponentName placeholder</div>
|
||||||
- Replace stub body entirely when implementing — no partial edits on stubs
|
- Replace stub body entirely when implementing — no partial edits on stubs
|
||||||
@@ -288,7 +331,8 @@ Runtime config
|
|||||||
|
|
||||||
- **React SPA**: explicit exception — this is a practitioner tool, not a public website.
|
- **React SPA**: explicit exception — this is a practitioner tool, not a public website.
|
||||||
No indexing needed. SPA is correct. (See BDR-001)
|
No indexing needed. SPA is correct. (See BDR-001)
|
||||||
- **No API versioning**: no backend, no API routes. Section N/A.
|
- **No API versioning**: no hand-written HTTP API. Supabase exposes tables/RPC through
|
||||||
|
PostgREST; breaking changes are handled by new migrations and RPC names, not URL versions.
|
||||||
- **80-char line limit**: relaxed to 100 for TypeScript generics and long Zod chains.
|
- **80-char line limit**: relaxed to 100 for TypeScript generics and long Zod chains.
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -313,6 +357,9 @@ Runtime config
|
|||||||
| @testing-library/react | Component testing utilities |
|
| @testing-library/react | Component testing utilities |
|
||||||
| @testing-library/jest-dom | Custom DOM matchers |
|
| @testing-library/jest-dom | Custom DOM matchers |
|
||||||
| eslint 9 | Linting (flat config) |
|
| eslint 9 | Linting (flat config) |
|
||||||
|
| @supabase/supabase-js 2 | Typed client (packages/supabase) |
|
||||||
|
| supabase (CLI) 2.120 | Local stack, migrations, pgTAP runner, type generation |
|
||||||
|
| @electric-sql/pglite 0.3 | PostgreSQL 17 in WASM: runs the pgTAP suite without Docker |
|
||||||
| prettier 3 | Code formatting |
|
| prettier 3 | Code formatting |
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -327,11 +374,13 @@ Runtime config
|
|||||||
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
|
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
|
||||||
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then DecompressionStream inflation.
|
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then DecompressionStream inflation.
|
||||||
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
||||||
|
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
|
||||||
|
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
|
||||||
|
|
||||||
## Commit message convention
|
## Commit message convention
|
||||||
|
|
||||||
Conventional Commits format. Subject ≤72 chars, imperative mood, no trailing period.
|
Conventional Commits format. Subject ≤72 chars, imperative mood, no trailing period.
|
||||||
Allowed scopes: `schema`, `store`, `anatomy`, `pdf`, `editor`, `home`, `new`, `ui`, `config`, `species`, `i18n`, `docker`, `docs`, `tests`, `chore`, `app`, `workspace`, `ci`.
|
Allowed scopes: `schema`, `store`, `anatomy`, `pdf`, `editor`, `home`, `new`, `ui`, `config`, `species`, `i18n`, `docker`, `docs`, `tests`, `chore`, `app`, `workspace`, `ci`, `supabase`, `domain`, `worker`, `public-web`.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
- `test(schema): cover Report version literal`
|
- `test(schema): cover Report version literal`
|
||||||
|
|||||||
@@ -36,9 +36,13 @@ each one explicitly.
|
|||||||
| `APP_BRAND_NAME` | yes | `Faunosteo` | Header brand block, PDF header. Praticien-visible identity. |
|
| `APP_BRAND_NAME` | yes | `Faunosteo` | Header brand block, PDF header. Praticien-visible identity. |
|
||||||
| `APP_FOOTER_NAME` | yes | `Faunosteo` | Footer copyright line. |
|
| `APP_FOOTER_NAME` | yes | `Faunosteo` | Footer copyright line. |
|
||||||
| `APP_TAGLINE` | yes | `Outils pour ostéopathes animaliers` | Hero tagline on Home. |
|
| `APP_TAGLINE` | yes | `Outils pour ostéopathes animaliers` | Hero tagline on Home. |
|
||||||
|
| `APP_SUPABASE_URL` | no | empty | Supabase project URL exposed to the browser. Empty = app runs without backend (current mode). |
|
||||||
|
| `APP_SUPABASE_ANON_KEY` | no | empty | Supabase anon (publishable) key. Public by design, data stays behind RLS. Never the service_role key. |
|
||||||
| `PORT` | no | `8080` | Container listen port. Must be `>=1024` — the container runs as a non-root `nginx` user and cannot bind privileged ports. |
|
| `PORT` | no | `8080` | Container listen port. Must be `>=1024` — the container runs as a non-root `nginx` user and cannot bind privileged ports. |
|
||||||
|
|
||||||
No secrets are required — there is no API, no DB, no provider credential.
|
No secrets are required in this file: the anon key is public by design and
|
||||||
|
the service_role key never leaves the Supabase host (see
|
||||||
|
`docs/development/SUPABASE.md`).
|
||||||
The `.env` file is not sensitive but should still be `chmod 600` to keep
|
The `.env` file is not sensitive but should still be `chmod 600` to keep
|
||||||
local identity overrides private.
|
local identity overrides private.
|
||||||
|
|
||||||
|
|||||||
@@ -39,7 +39,7 @@ contract.
|
|||||||
|
|
||||||
## Stack
|
## Stack
|
||||||
|
|
||||||
- Node.js 20
|
- Node.js 24 LTS + pnpm 10.13 (corepack)
|
||||||
- React 19 + TypeScript 5 (strict)
|
- React 19 + TypeScript 5 (strict)
|
||||||
- Vite 7 + @vitejs/plugin-react-swc
|
- Vite 7 + @vitejs/plugin-react-swc
|
||||||
- Tailwind CSS v4 (CSS-first, no postcss config)
|
- Tailwind CSS v4 (CSS-first, no postcss config)
|
||||||
@@ -48,6 +48,7 @@ contract.
|
|||||||
- pdf-lib 1.17 (PDF generation + native attachments)
|
- pdf-lib 1.17 (PDF generation + native attachments)
|
||||||
- motion 11 (animations)
|
- motion 11 (animations)
|
||||||
- vitest 3 + happy-dom + @testing-library/react
|
- vitest 3 + happy-dom + @testing-library/react
|
||||||
|
- Supabase (PostgreSQL 17, Auth, RLS) via the pinned CLI; `@supabase/supabase-js` 2; PGlite for Dockerless SQL tests
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -79,7 +80,7 @@ docker compose up --build
|
|||||||
```bash
|
```bash
|
||||||
pnpm typecheck # TypeScript strict, no emit
|
pnpm typecheck # TypeScript strict, no emit
|
||||||
pnpm lint # ESLint 9 flat config, 0 warnings
|
pnpm lint # ESLint 9 flat config, 0 warnings
|
||||||
pnpm test:run # vitest run (271 tests)
|
pnpm test:run # vitest run (app 278 + supabase 13, incl. 79 pgTAP checks on PGlite)
|
||||||
pnpm build # tsc + vite build → apps/app/dist/
|
pnpm build # tsc + vite build → apps/app/dist/
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -104,6 +105,7 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy,
|
|||||||
- [docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) — guide for adding a second species post-MVP
|
- [docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) — guide for adding a second species post-MVP
|
||||||
- [docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md) — findings catalog format + authoring guide
|
- [docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md) — findings catalog format + authoring guide
|
||||||
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract
|
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract
|
||||||
|
- [docs/development/SUPABASE.md](docs/development/SUPABASE.md) — local Supabase stack, migrations, RLS tests, generated types
|
||||||
- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening)
|
- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening)
|
||||||
- [CHANGELOG.md](CHANGELOG.md) — versioned release notes
|
- [CHANGELOG.md](CHANGELOG.md) — versioned release notes
|
||||||
- [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — implementation roadmap
|
- [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — implementation roadmap
|
||||||
@@ -127,7 +129,8 @@ faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md)
|
|||||||
├─ src/lib/ id, dates, assert utilities
|
├─ src/lib/ id, dates, assert utilities
|
||||||
├─ src/styles/ Tailwind v4 CSS + design tokens
|
├─ src/styles/ Tailwind v4 CSS + design tokens
|
||||||
├─ tests/unit/ vitest tests (apps/app/tests, incl. characterisation suite)
|
├─ tests/unit/ vitest tests (apps/app/tests, incl. characterisation suite)
|
||||||
├─ packages/ shared packages, none yet
|
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL test harness
|
||||||
|
├─ supabase/ CLI config, SQL migrations, local seed, pgTAP tests
|
||||||
├─ docker/ entrypoint.sh + nginx.conf
|
├─ docker/ entrypoint.sh + nginx.conf
|
||||||
├─ docs/ conventions + species guide + PDF spec
|
├─ docs/ conventions + species guide + PDF spec
|
||||||
├─ index.html SPA entry point
|
├─ index.html SPA entry point
|
||||||
|
|||||||
@@ -0,0 +1,184 @@
|
|||||||
|
# Supabase: local stack, migrations, tests
|
||||||
|
|
||||||
|
Status: Step 3 deliverable, 2026-10-08. Covers the foundation only (profiles,
|
||||||
|
platform roles, audit log). Conventions: `BACKEND_ARCHITECTURE.md` §3–§9.
|
||||||
|
|
||||||
|
## 1. Layout
|
||||||
|
|
||||||
|
```text
|
||||||
|
supabase/
|
||||||
|
├─ config.toml CLI config (public schema exposed only, PG 17, strong passwords)
|
||||||
|
├─ migrations/ forward-only SQL, <timestamp>_<name>.sql
|
||||||
|
│ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log
|
||||||
|
│ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS
|
||||||
|
│ └─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs
|
||||||
|
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
|
||||||
|
└─ tests/ pgTAP, one file per concern, allowed AND denied paths
|
||||||
|
packages/supabase/
|
||||||
|
├─ src/client.ts createBrowserClient() (anon key, PKCE)
|
||||||
|
├─ src/database.types.ts `supabase gen types` output
|
||||||
|
└─ tests/db/ PGlite harness: runs the pgTAP files without Docker
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Prerequisites
|
||||||
|
|
||||||
|
- Node 24 + pnpm via corepack (`WORKSPACE.md`).
|
||||||
|
- Docker daemon reachable by your user for the real stack. If `docker info`
|
||||||
|
says `permission denied ... docker.sock`, add yourself to the `docker`
|
||||||
|
group and log in again:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo usermod -aG docker "$USER"
|
||||||
|
```
|
||||||
|
|
||||||
|
- No Docker: the PGlite suite still runs (see §5), the CLI commands do not.
|
||||||
|
|
||||||
|
The Supabase CLI is a root devDependency (`pnpm supabase <cmd>`), pinned
|
||||||
|
like every other tool. Never install it globally.
|
||||||
|
|
||||||
|
## 3. Start, stop, reset
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys
|
||||||
|
pnpm db:stop # supabase stop (keeps the volume)
|
||||||
|
pnpm db:reset # drop + replay every migration + seed from zero
|
||||||
|
```
|
||||||
|
|
||||||
|
Local endpoints (`config.toml`):
|
||||||
|
|
||||||
|
| Service | URL |
|
||||||
|
|---|---|
|
||||||
|
| API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` |
|
||||||
|
| PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` |
|
||||||
|
| Studio | `http://127.0.0.1:54323` |
|
||||||
|
| Mail catcher (confirmation / OTP mails) | `http://127.0.0.1:54324` |
|
||||||
|
|
||||||
|
`pnpm db:start` prints the `anon` and `service_role` keys. Only the anon key
|
||||||
|
ever reaches the browser.
|
||||||
|
|
||||||
|
Seed accounts (local only, password `LocalDev-only-password-1`):
|
||||||
|
|
||||||
|
| Email | Role |
|
||||||
|
|---|---|
|
||||||
|
| `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) |
|
||||||
|
| `alice@faunosteo.local` | plain user |
|
||||||
|
| `bob@faunosteo.local` | plain user |
|
||||||
|
|
||||||
|
## 4. Writing a migration
|
||||||
|
|
||||||
|
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`.
|
||||||
|
2. A migration that adds a table adds, in the same file: RLS enable, explicit
|
||||||
|
`revoke all ... from public, anon, authenticated` then the exact grants,
|
||||||
|
separate SELECT / INSERT / UPDATE / DELETE policies, indexes, comments.
|
||||||
|
3. Add or extend a pgTAP file under `supabase/tests/`: the allowed path and
|
||||||
|
every denied path (other user, anon, direct write bypassing an RPC).
|
||||||
|
4. `pnpm --filter @faunosteo/supabase test:run` (PGlite, seconds), then
|
||||||
|
`pnpm db:reset && pnpm db:test` on the real stack.
|
||||||
|
5. `pnpm db:types` and commit `packages/supabase/src/database.types.ts`.
|
||||||
|
6. Never edit an applied migration. Corrections are new migrations.
|
||||||
|
|
||||||
|
Rules enforced by the schema-types test for every future `public` table:
|
||||||
|
RLS enabled, no `using (true)` / `with check (true)` policy for `anon` or
|
||||||
|
`authenticated`.
|
||||||
|
|
||||||
|
## 5. Tests
|
||||||
|
|
||||||
|
Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP):
|
||||||
|
|
||||||
|
| Command | Engine | Needs Docker | What runs |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema + all migrations + every pgTAP file; schema ↔ types check; client factory |
|
||||||
|
| `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image |
|
||||||
|
|
||||||
|
`pnpm test:run` at the root runs the PGlite suite together with the app
|
||||||
|
suite. The shim (`packages/supabase/tests/db/supabase-shim.sql`) recreates
|
||||||
|
the API roles, `auth.users`, `auth.uid()` and the permissive default
|
||||||
|
privileges of Supabase so that a forgotten `revoke` fails a test.
|
||||||
|
|
||||||
|
How a test impersonates a user (same technique in both runners):
|
||||||
|
|
||||||
|
```sql
|
||||||
|
set local role authenticated;
|
||||||
|
select set_config('request.jwt.claims', '{"sub":"<user uuid>","role":"authenticated"}', true);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Generated types
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm db:types # regenerate packages/supabase/src/database.types.ts (local stack running)
|
||||||
|
pnpm db:types:check # CI: fail on any diff
|
||||||
|
```
|
||||||
|
|
||||||
|
The schema-types test checks tables, columns, enum labels and RPC argument
|
||||||
|
names against the migrated schema, so a stale file fails before CI.
|
||||||
|
|
||||||
|
## 7. First platform owner in a real environment
|
||||||
|
|
||||||
|
The RPCs refuse self-grants and need an existing owner or admin. The first
|
||||||
|
owner is created once, from a privileged SQL session (service connection,
|
||||||
|
`psql` on the host), never from the browser:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
select private.assign_platform_role(null, '<auth.users.id of the owner>', 'owner');
|
||||||
|
```
|
||||||
|
|
||||||
|
The call is audited with a null actor. Afterwards every role change goes
|
||||||
|
through `grant_platform_role` / `revoke_platform_role`.
|
||||||
|
|
||||||
|
## 8. Manual validation (Definition of Done: "an authenticated request hits a protected table safely")
|
||||||
|
|
||||||
|
```bash
|
||||||
|
URL=http://127.0.0.1:54321
|
||||||
|
ANON=<anon key printed by pnpm db:start>
|
||||||
|
|
||||||
|
token() { # $1 = email
|
||||||
|
curl -s -X POST "$URL/auth/v1/token?grant_type=password" \
|
||||||
|
-H "apikey: $ANON" -H "Content-Type: application/json" \
|
||||||
|
-d "{\"email\":\"$1\",\"password\":\"LocalDev-only-password-1\"}" | jq -r .access_token
|
||||||
|
}
|
||||||
|
ALICE=$(token alice@faunosteo.local); OWNER=$(token owner@faunosteo.local)
|
||||||
|
ALICE_ID=10000000-0000-0000-0000-00000000000a
|
||||||
|
|
||||||
|
# 1. alice reads exactly one profile (hers)
|
||||||
|
curl -s "$URL/rest/v1/profiles?select=id,display_name" -H "apikey: $ANON" -H "Authorization: Bearer $ALICE"
|
||||||
|
|
||||||
|
# 2. anon reads nothing (permission denied)
|
||||||
|
curl -s "$URL/rest/v1/profiles" -H "apikey: $ANON"
|
||||||
|
|
||||||
|
# 3. alice cannot deactivate herself (column privilege) nor self-grant admin
|
||||||
|
curl -s -X PATCH "$URL/rest/v1/profiles?id=eq.$ALICE_ID" -H "apikey: $ANON" \
|
||||||
|
-H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" -d '{"active":false}'
|
||||||
|
curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \
|
||||||
|
-H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" \
|
||||||
|
-d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"admin\"}"
|
||||||
|
|
||||||
|
# 4. the owner grants moderator to alice; the grant is audited
|
||||||
|
curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \
|
||||||
|
-H "Authorization: Bearer $OWNER" -H "Content-Type: application/json" \
|
||||||
|
-d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"moderator\"}"
|
||||||
|
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \
|
||||||
|
-c "select actor_user_id, action, target_user_id, metadata from audit.audit_logs order by occurred_at"
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: 1 → one row; 2 → `42501`; 3 → both `42501`; 4 → a uuid, then two
|
||||||
|
audit rows (bootstrap with null actor, grant by the owner).
|
||||||
|
|
||||||
|
## 9. Wiring the app
|
||||||
|
|
||||||
|
`.env` (Docker) or `apps/app/.env.local` (Vite dev):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
APP_SUPABASE_URL=http://127.0.0.1:54321 # VITE_SUPABASE_URL in dev
|
||||||
|
APP_SUPABASE_ANON_KEY=<anon key> # VITE_SUPABASE_ANON_KEY in dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Both empty (the default) keeps the app in its current local-only mode:
|
||||||
|
`getSupabaseClient()` returns null. No screen uses the client yet.
|
||||||
|
|
||||||
|
## 10. Self-hosted parity
|
||||||
|
|
||||||
|
The local stack runs the same images as a self-hosted deployment
|
||||||
|
(`supabase/docker` compose), so migrations, policies and tests transfer
|
||||||
|
unchanged. The self-hosted runbook (VPS sizing, secrets, backups, TLS) is a
|
||||||
|
separate deliverable once the hosting question (OPEN_QUESTIONS Q2) is
|
||||||
|
settled; it reuses `pnpm supabase db push --db-url <...>` for migrations.
|
||||||
@@ -13,7 +13,8 @@ faunosteo/
|
|||||||
│ ├─ src/ public/ tests/ scripts/ index.html
|
│ ├─ src/ public/ tests/ scripts/ index.html
|
||||||
│ ├─ vite.config.ts vitest.config.ts tsconfig*.json eslint.config.js
|
│ ├─ vite.config.ts vitest.config.ts tsconfig*.json eslint.config.js
|
||||||
│ └─ package.json app dependencies and scripts
|
│ └─ package.json app dependencies and scripts
|
||||||
├─ packages/ shared code, empty on purpose (see packages/README.md)
|
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL tests
|
||||||
|
├─ supabase/ Supabase CLI config, migrations, seed, pgTAP tests (docs/development/SUPABASE.md)
|
||||||
├─ docker/ nginx.conf, entrypoint.sh (unchanged)
|
├─ docker/ nginx.conf, entrypoint.sh (unchanged)
|
||||||
├─ docs/ conventions, audit, development plan
|
├─ docs/ conventions, audit, development plan
|
||||||
├─ logos/ brand sources
|
├─ logos/ brand sources
|
||||||
|
|||||||
+4
-4
@@ -1,8 +1,8 @@
|
|||||||
# packages/
|
# packages/
|
||||||
|
|
||||||
Shared code lives here once it has a real owner and real content. Nothing is
|
Shared code lives here once it has a real owner and real content: an empty
|
||||||
extracted yet: an empty package would only add build configuration to maintain
|
package would only add build configuration to maintain (IMPLEMENTATION_PLAN.md
|
||||||
(IMPLEMENTATION_PLAN.md Step 2, FRONTEND_ARCHITECTURE.md §6).
|
Step 2, FRONTEND_ARCHITECTURE.md §6). First package: `supabase/` (Step 3).
|
||||||
|
|
||||||
Planned packages and the step that creates each one:
|
Planned packages and the step that creates each one:
|
||||||
|
|
||||||
@@ -12,7 +12,7 @@ Planned packages and the step that creates each one:
|
|||||||
| `@faunosteo/anatomy` | SVG convention parser, legacy importer, renderer helpers, spine logic | Step 4 |
|
| `@faunosteo/anatomy` | SVG convention parser, legacy importer, renderer helpers, spine logic | Step 4 |
|
||||||
| `@faunosteo/pdf` | export / import / attachment, render helpers | Step 6 (PDF v3) |
|
| `@faunosteo/pdf` | export / import / attachment, render helpers | Step 6 (PDF v3) |
|
||||||
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
|
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
|
||||||
| `@faunosteo/supabase` | client factories, generated database types, typed RPC wrappers | Step 3 (Supabase foundation) |
|
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite | **created**, Step 3 |
|
||||||
| `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |
|
| `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |
|
||||||
| `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |
|
| `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user