85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 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
|