mc_cars_gmbh_infraestructure/AGENT.md

AGENT.md – Operational notes for working on MC Cars

A compact field guide for anyone (human or AI) making changes to this stack. Skim this first.

---

1. The portability contract (don't break it)

1. No named volumes. All runtime state bind-mounts to ./data/. docker compose down -v must never be required to migrate: copy the folder, docker compose up -d, done.
2. No absolute paths in docker-compose.yml or any config.
3. Secrets live in .env; the .env ships with dev defaults and is safe to commit until real deploy. Any non-local deployment must rotate every key (see §6).
4. Anything that resets the DB in dev is Remove-Item -Recurse -Force .\data — not docker volume rm.

---

2. Migration lifecycle

Migrations come in two flavours:

First-boot only (runs iff ./data/db is empty)

• supabase/migrations/00-run-init.sh — wrapper that runs 01-init.sql via psql so we can pre-create Supabase service roles (anon, authenticated, service_role, authenticator, supabase_auth_admin, supabase_storage_admin) that the official images otherwise assume already exist on their supabase/postgres image. We use plain postgres:15-alpine, so we create them ourselves.
• supabase/migrations/01-init.sql — vehicles table, RLS, bucket row, seed demo vehicles.

Postgres' official entrypoint only processes /docker-entrypoint-initdb.d/ on an empty data dir. To re-run: wipe ./data/db.

Post-boot (every time, idempotent)

• supabase/migrations/post-boot.sql — seeds the admin auth.users row with must_change_password=true, creates the vehicle-photos bucket row if missing. Parameterized: psql -v admin_email=... -v admin_password=....
• supabase/migrations/02-leads.sql — leads + customers + RPCs + supabase_realtime publication. Uses create if not exists, create or replace, and do $$ ... $$ with exists-checks so every object is idempotent.

Both are run by the post-init service, which gates on auth.users and storage.buckets being queryable before touching anything.

Adding a new migration:

• If it's schema the app can't start without on a fresh DB → extend 01-init.sql.
• If it's ongoing / idempotent → new file 03-*.sql, mount it in post-init, append one more psql -f line to the entrypoint.

---

3. Roles, RLS, and the mental model

Role	How obtained	Can do
anon	Anon JWT (shipped to browser)	select on active vehicles; insert on leads only
authenticated	JWT from signInWithPassword	Full CRUD on vehicles/leads/customers, execute RPCs
service_role	Service JWT (never in browser)	Bypasses RLS

• Anon cannot read leads. The booking form is fire-and-forget by design. An abuser submitting with a stolen anon key sees only HTTP 201 with no row data.
• RPCs are SECURITY INVOKER. They run as the caller, so auth.uid() returns the actual admin; RLS still applies.
• qualify_lead is idempotent — calling it twice returns the existing customer row instead of raising.

---

4. Realtime wiring

• Postgres command line forces wal_level=logical, max_wal_senders=10, max_replication_slots=10. Without logical, supabase/realtime crash-loops.
• supabase/realtime:v2.30.23 connects as DB_USER=postgres (not supabase_admin). We're on the plain postgres:15-alpine image; the supabase_admin role does not exist.
• SECRET_KEY_BASE must be ≥ 64 chars; the hardcoded value in docker-compose.yml is a dev default — rotate it on real deploys.
• Replica identity full is set on leads/customers/vehicles so updates broadcast the complete row, not just the PK.
• Kong route /realtime/v1/ → http://realtime:4000/socket (websocket upgrade headers handled by Kong's default config).

---

5. Kong traps

• On Windows/WSL2, Docker Desktop's wslrelay intercepts 127.0.0.1:8000. We expose Kong on host 54321 (container 8000). Don't move it back to 8000.
• Kong needs KONG_PLUGINS: bundled,request-transformer,cors,key-auth,acl,basic-auth. Omitting acl breaks Studio.
• kong.yml has one consumer per role with acl groups; plugins key-auth + acl gate which apikey (anon vs service_role) can reach which route.

---

6. Password rotation & admin bootstrap

The .env ADMIN_PASSWORD is a one-shot bootstrap seed. On first login:

1. admin.js reads user.user_metadata.must_change_password.
2. If true, the UI shows the "Passwort setzen" screen and refuses to proceed.
3. Submit calls supabase.auth.updateUser({ password, data: { must_change_password: false } }).
4. The frontend also rejects newPassword === loginPassword before sending.

Result: the live admin password differs from .env from the very first session. The .env value is useful only for a brand-new ./data/db.

Password min length is enforced server-side by GOTRUE_PASSWORD_MIN_LENGTH=10.

---

7. Frontend conventions

• Only the anon key leaves the server. frontend/Dockerfile writes config.js at container start from $SUPABASE_URL / $SUPABASE_ANON_KEY. The service_role key is not mounted into web.
• frontend/app.js (public) creates a Supabase client with persistSession: false — the public site never needs a session.
• frontend/admin.js uses persistSession: true, storageKey: "mccars.auth" and a single realtime channel mccars-admin that subscribes to leads/customers/vehicles.
• app.js writes vehicle_id (uuid) and denormalized vehicle_label ("BMW M3") into the lead at submit time, so the admin UI renders even if the vehicle is later deleted.

---

8. Common failure modes

Symptom	Cause / Fix
auth container restart loop, "role supabase_auth_admin does not exist"	00-run-init.sh didn't run. Wipe ./data/db, retry.
realtime container exits, "wal_level must be logical"	db command: missing wal_level=logical.
502 on /realtime/v1/ through Kong	Missing acl plugin in KONG_PLUGINS, or realtime not listed in kong.yml consumers.
Admin login works but Leads tab is empty	RLS: session is anon instead of authenticated. Check that signInWithPassword succeeded and token is attached to subsequent requests.
Booking form submits but no row appears	anon lacks INSERT grant on public.leads. Check 02-leads.sql ran (see post-init logs).
.sh files reject with \r: command not found	CRLF line endings. dos2unix or re-save as LF.
Port 8000 "connection refused" on Windows	Docker Desktop wslrelay. Use 54321.

---

9. How to verify a working stack

docker compose ps                                            # all services up (post-init exited 0)
curl http://localhost:54321/rest/v1/vehicles?select=brand -H "apikey: $env:ANON" # 6 demo cars

In the browser:

1. Open http://localhost:8080, submit the booking form.
2. Open http://localhost:8080/admin.html, log in with .env bootstrap creds.
3. Rotate the password when prompted.
4. The lead you submitted appears in "Aktive Leads" — in real time.
5. Click Qualifizieren. Row disappears from active, a new row appears in Kunden with the lead_id displayed.
6. Open Supabase Studio at http://localhost:3000 and confirm the customers.lead_id FK matches.

---

10. Things explicitly NOT in this stack

• No n8n. Email automation is out of scope here; do it downstream.
• No Google Analytics / Google Reviews widget.
• No "Anmelden/Registrieren" on the public site. Admin access is intentionally unlinked.
• No logflare / analytics.
• No edge-functions container — RPCs live in Postgres.