docs: split CLAUDE.md into docs/{development,deployment,history/fase-*}

CLAUDE.md shrinks to rules + status + index (175 lines, down from 476). Dev setup, prod deploy, and per-phase build records move to docs/. Gotchas regrouped by domain (auth, frontend, PWA, testing, backend, deploy, platform) and unnumbered so they don't drift as new ones land. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-18 22:21:20 +02:00
parent 3d85d0a50e
commit 768b3cda58
11 changed files with 441 additions and 403 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -0,0 +1,93 @@
+# Development
+
+## Planned Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend / PWA | SvelteKit 2 + `@vite-pwa/sveltekit` + Workbox |
+| Auth / IdP | Keycloak self-hosted (OIDC/OAuth2) |
+| Backend / BaaS | Supabase self-hosted (GoTrue + Realtime + Storage + Kong) |
+| Database | PostgreSQL 15 (via Supabase) |
+| Offline storage | IndexedDB via `idb` |
+| Monorepo | Turborepo + pnpm workspaces |
+| Infra | Docker Compose (dev + prod) + nginx (prod, managed externally) |
+| CI/CD | GitHub Actions |
+
+## Planned Repository Layout
+
+```
+apps/web/src/lib/
+  supabase.ts          # Supabase singleton client (PKCE, GoTrue auth)
+  auth.ts              # login() / logout() via supabase.auth.signInWithOAuth (Keycloak provider)
+  stores/              # Svelte global stores
+  sync/                # offline queue + conflict resolution
+  components/          # reusable UI components
+apps/web/src/routes/   # SvelteKit file-based routes
+packages/types/src/
+  database.ts          # types generated from Supabase schema (never edit manually)
+  domain.ts            # domain types (Collective, ShoppingList, Item, etc.)
+supabase/
+  migrations/          # versioned SQL migrations
+  seed.sql             # dev test data (5 Keycloak users + sample collective)
+  functions/           # Edge Functions (invitations, etc.)
+  config.toml          # Supabase CLI config + Keycloak OIDC
+keycloak/
+  realm-export.json    # "colectivo" realm — imported on dev startup
+infra/
+  docker-compose.dev.yml
+  docker-compose.prod.yml
+  scripts/backup.sh / backup-cron.sh / restore.sh / deploy.sh
+```
+
+## Development Commands (Justfile)
+
+```bash
+just setup            # first-time (and idempotent) local environment setup
+just dev              # start docker-compose.dev.yml + SvelteKit dev server
+just serve            # build + start prod Node server at :3000 against dev Docker stack
+just stop             # stop all services (Docker stack + Vite dev server)
+just dev-stop         # stop Docker stack only
+just dev-clean        # stop Docker stack and remove all volumes (full reset)
+just db-reset         # drop + migrate + seed (dev)
+just db-migrate       # apply pending migrations (dev)
+just db-seed          # apply supabase/seed.sql to the running dev db
+just db-types         # regenerate TS types from Supabase schema → packages/types
+just kc-export        # export Keycloak realm → keycloak/realm-export.json
+just kc-open          # open Keycloak Admin Console (localhost:8080)
+just deploy           # run infra/scripts/deploy.sh (prod)
+just backup supabase           # immediate manual backup
+just restore supabase <file>   # restore a specific dump
+just logs             # docker compose logs -f (prod)
+```
+
+## Test Commands
+
+```bash
+just test-all            # run every suite (pgTAP + Vitest + Playwright) — requires just dev running
+just test-integration    # Vitest RLS tests (requires just dev stack running)
+just test-db             # pgTAP SQL tests (requires just dev stack running)
+just test-e2e            # Playwright E2E tests (requires just dev running)
+just test-e2e-headed     # Playwright with visible browser (debugging)
+just test-rate-limit     # gated Kong rate-limit test (RL-02); force-recreates Kong first
+```
+
+## Local Dev Endpoints and Credentials
+
+| Service | URL | Credentials (dev only) |
+|---|---|---|
+| SvelteKit app | http://localhost:5173 | — |
+| Supabase Studio | http://localhost:54323 | — |
+| Supabase API (Kong) | http://localhost:8001 | apikey: `PUBLIC_SUPABASE_ANON_KEY` from `.env` |
+| Keycloak Admin | http://localhost:8080/admin | `admin` / `admin` |
+| PostgreSQL | localhost:5432 | `postgres` / `postgres` |
+
+## Dev Secrets
+
+Set in `.env`, never commit to prod:
+
+| Variable | Dev value |
+|---|---|
+| `POSTGRES_PASSWORD` | `postgres` |
+| `SUPABASE_JWT_SECRET` | `super-secret-jwt-token-with-at-least-32-characters-long` |
+| `KEYCLOAK_ADMIN` / `KEYCLOAK_ADMIN_PASSWORD` | `admin` / `admin` |
+| `KEYCLOAK_CLIENT_SECRET` | `gotrue-dev-secret` (client secret for `colectivo-web` in GoTrue) |