Oier Bravo Urtasun
768b3cda58
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>
3.9 KiB
3.9 KiB
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)
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
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) |