Files

T

joshuaandClaude Opus 5.5 c89a82295b Phase 0: scaffold Next.js, Tailwind tokens, Supabase clients, env validation

Next.js 16 App Router with strict TypeScript, Tailwind 4 theme tokens from
docs/UI.md, Vitest, and the three Supabase clients. Env vars are validated
with zod in next.config.ts so dev and build fail fast with a readable error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-03 12:27:11 +02:00

2.5 KiB

Raw Blame History

CLAUDE.md — Game Night Live

You are building a live scoring web app for a church youth group's game nights. Read docs/ before writing code. Docs are the source of truth; if code and docs disagree, ask.

Stack (do not swap without asking)

Next.js (App Router, latest stable) + TypeScript (strict)
Tailwind CSS
Supabase: Postgres, Auth (admin only, email magic link), Realtime (Broadcast)
zod for all input validation
Vitest for unit tests (scoring logic MUST be tested)
npm as package manager
Deploy target: Vercel

Verify current Next.js and Supabase APIs against their official docs before using them; don't rely on memory for SDK method names (esp. @supabase/ssr and Realtime broadcast from the server).

Non-negotiable rules

The service role key is server-only. Never import it in a client component. Never prefix it NEXT_PUBLIC_.
Anon users get zero table access. RLS is on for every table. Scoreboard and judge pages read/write ONLY through Next.js route handlers that validate the token and use the service-role client.
Hiding the scoreboard is enforced on the server. When hidden, the scoreboard API must not return scores at all. Never hide with CSS only — someone will open devtools.
Realtime messages carry no data. Broadcast a { type: "refresh" } ping; clients refetch from the API. This keeps hidden/sanitised data rules in one place.
One scoring engine. All score math lives in src/lib/scoring/ as pure functions with tests. Admin view, scoreboard API and judge view all call it. No score math in components or SQL views.
Tokens are unguessable (≥ 128 bits, hex). Validate shape with zod before hitting the DB.
Mobile-first for judge pages (they're on phones). Scoreboard is 16:9 projector-first.
Small commits per task. After each phase, stop and summarise what to test manually.

Code conventions

src/app routes, src/lib logic, src/components UI, src/lib/supabase/{server,admin,browser}.ts clients.
Server actions for admin mutations; route handlers (src/app/api/...) for public/judge.
Every mutation that affects scores/visibility calls notify() from src/lib/realtime.ts which pings the relevant channels (see ARCHITECTURE.md).
Use DB types generated by supabase gen types typescript.
Explain why in PR-style summaries, not just what changed.

Commands

npm run dev / npm run build / npm run test / npm run lint
Migrations live in supabase/migrations/. Apply via Supabase CLI or paste into SQL editor.