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>
94 lines
3.9 KiB
Markdown
94 lines
3.9 KiB
Markdown
# 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) |
|