# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Référence d'architecture complète : voir `ARCHITECTURE.md` à la racine.

## What is NerdWare

Party game web multi-épreuves, ambiance WarioWare, centré culture geek (jeux vidéo, manga, pop culture). Chaque joueur joue sur son propre PC, rooms synchronisées en temps réel via Socket.IO. V1 = Blindtest (YouTube) + Quiz culture.

## Common Commands

```bash
bun install              # Install all workspace dependencies (NEVER use npm/pnpm/yarn)
bun run dev              # Start all apps/packages in dev mode (Turborepo)
bun run build            # Build everything
bun run lint             # Lint all workspaces
bun run typecheck        # Type-check all workspaces
bun run format           # Format all workspaces with Prettier

# Per-workspace (from root)
bun run --filter web dev        # Dev server for client only
bun run --filter @nerdware/server dev   # Dev server for backend only (once created)

# Per-workspace (from workspace dir)
cd apps/web && bun run dev
```

## Monorepo Structure

Turborepo + Bun workspaces. Convention `apps/*` (runnable) + `packages/*` (shared libraries).

- `apps/web` — Vite + React client (`web` in package.json, imports `@workspace/ui`)
- `packages/ui` — shadcn/ui components (`@workspace/ui`), exports via `./components/*`, `./lib/*`, `./hooks/*`, `./globals.css`
- `apps/server` — **TO CREATE** — Fastify + Socket.IO backend (`@nerdware/server`)
- `packages/shared` — **TO CREATE** — Shared WS event types + domain (`@nerdware/shared`), imported by both web and server

## Stack Constraints — DO NOT suggest alternatives

These choices are final. Never suggest Express, Prisma, Next.js, Spotify for audio, npm/pnpm/yarn, or any replacement.

| Layer | Choice |
|---|---|
| Language | TypeScript (strict, front + back) |
| Package manager / runtime | **Bun** |
| Monorepo | Turborepo |
| Backend | Fastify + Socket.IO |
| DB | PostgreSQL + Drizzle ORM (quiz content + history only; rooms live in-memory) |
| Frontend | Vite + React |
| Routing | wouter |
| Client state | Zustand (mirrors state pushed by Socket.IO) |
| HTTP data fetching | TanStack Query (back-office quiz + auth ONLY, NOT real-time game) |
| UI | Tailwind v4 + shadcn/ui (Radix), Lucide icons |
| Fonts | Outfit (body) + Oxanium (headings/arcade), self-hosted via Fontsource |
| Animations | Framer Motion |
| Audio | YouTube IFrame Player API (not Spotify) |
| Images | Docker volume served statically by Fastify (no S3/MinIO in V1) |

## Architecture Principles (non-negotiable)

1. **Authoritative server.** Timer, scores, round order, DJ selection — all server-side. Client only displays received state. Never trust the client.
2. **Shared WS types.** All Socket.IO events typed in `packages/shared`, imported by both sides. Malformed event = compile error.
3. **Generic game engine.** Each game mode implements the same `GameRound` interface (`start / submitAnswer / reveal / score`). Adding a game mode = one module, no plumbing changes.
4. **In-memory rooms.** Server-side `Map`. No Redis in V1.
5. **Round ends** on first condition met: timer expired OR all eligible votes received.

## Code Conventions

- No semicolons, double quotes, trailing commas `es5`, 2-space indent (see `.prettierrc`)
- Prettier with `prettier-plugin-tailwindcss` (functions: `cn`, `cva`)
- ESLint flat config (`eslint.config.js` per workspace)
- TS strict mode. No unjustified `any`.
- Package names: `@nerdware/*` (note: `packages/ui` is currently `@workspace/ui` from shadcn preset)
- Env vars for secrets (YouTube API keys, DB) — never hardcoded

## Implementation Order (V1 roadmap)

1. Create `packages/shared` (domain types + WS events) and `apps/server` (Fastify + Socket.IO startup)
2. First real-time cycle: `room:create` / `room:join` + `room:state` broadcast + minimal lobby client
3. Generic game engine (`GameRound` interface + orchestration loop + server timer)
4. Quiz game mode end-to-end (simplest — no DJ, no audio)
5. Drizzle setup + schema + Open Trivia DB seed
6. Blindtest game mode (YouTube audio sync + DJ role) — highest technical risk
7. Manual quiz back-office
8. Polish: Framer Motion animations, transition screens, end-game + Spotify export