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

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)

Authoritative server. Timer, scores, round order, DJ selection — all server-side. Client only displays received state. Never trust the client.
Shared WS types. All Socket.IO events typed in packages/shared, imported by both sides. Malformed event = compile error.
Generic game engine. Each game mode implements the same GameRound interface (start / submitAnswer / reveal / score). Adding a game mode = one module, no plumbing changes.
In-memory rooms. Server-side Map. No Redis in V1.
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)

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

4.2 KiB Raw Blame History