nerdware/README.md

# NerdWare

Party game web multi-épreuves, ambiance WarioWare, centré culture geek (jeux
vidéo, manga, pop culture). Chaque joueur joue sur son propre PC/téléphone, les
rooms sont synchronisées en temps réel via Socket.IO.

**Quiz culture · Images (révélation) · Blindtest (YouTube)**, mélangeables dans
une même partie. Interface FR / EN, reconnexion après refresh, bots pour jouer à
plusieurs tout seul.

> Architecture détaillée : [`ARCHITECTURE.md`](./ARCHITECTURE.md) · consignes de
> dev : [`CLAUDE.md`](./CLAUDE.md).

## Stack

| Couche | Choix |
|---|---|
| Langage | TypeScript (strict, front + back) |
| Runtime / package manager | **Bun** |
| Monorepo | Turborepo |
| Backend | Fastify + Socket.IO |
| DB | PostgreSQL + Drizzle ORM (contenu quiz + historique ; rooms en mémoire) |
| Frontend | Vite + React, wouter, Zustand, TanStack Query (back-office) |
| UI | Tailwind v4 + shadcn/ui, Framer Motion, Lucide |
| Audio | YouTube IFrame Player API |
| Avatars | DiceBear (style lorelei), générés en local |

## Structure

```
apps/
  web/      Client Vite + React (jeu + back-office)
  server/   Fastify + Socket.IO + Drizzle (moteur de jeu autoritaire)
packages/
  shared/   Types de domaine + events WS partagés (@nerdware/shared)
  ui/       Composants shadcn/ui (@workspace/ui)
```

Le serveur est **autoritaire** : timer, scores, ordre des manches et tirage du
DJ sont tranchés côté serveur ; le client n'affiche que l'état reçu. Chaque
épreuve implémente l'interface `GameRound` (`start / submitAnswer / reveal /
score`) — ajouter un mode = un module, sans toucher à la plomberie.

## Démarrer

Prérequis : [Bun](https://bun.sh) ≥ 1.3, et [Docker](https://www.docker.com)
pour la base (optionnel — sans DB, le quiz tourne sur une banque en dur).

```bash
bun install

# (optionnel) base de données
docker compose up -d
cd apps/server && cp .env.example .env
bun run db:migrate      # applique les migrations
bun run db:seed         # seed Open Trivia DB (~1 req/5s) + banque FR
bun run db:seed:images  # (optionnel) seed images via PokéAPI (mode Images)
cd ../..

# config client
cd apps/web && cp .env.example .env && cd ../..

# tout lancer (Turborepo)
bun run dev
```

- Client : http://localhost:5173
- Serveur : http://localhost:3001

Crée une room, choisis ton pseudo, partage le **lien d'invitation**, et lancez
une partie (quiz, blindtest ou mixte).

## Scripts (racine)

```bash
bun run dev         # tout en dev
bun run build       # build complet
bun run lint        # lint
bun run typecheck   # type-check
bun run test        # tests (bun test)
bun run format      # prettier
```

Serveur (`apps/server`) : `db:generate`, `db:migrate`, `db:seed`, `db:studio`.

## Modes de jeu

- **Quiz** — QCM, vrai/faux, et réponse libre (matching tolérant). Bonus de
  rapidité. Questions issues d'Open Trivia DB (seed) ou du back-office.
- **Images** — une image se dé-floute progressivement, on devine le sujet
  (réponse libre). Seed PokéAPI ou images uploadées dans le back-office.
- **Blindtest** — chaque joueur soumet des liens YouTube ; un DJ neutre pilote
  la lecture, les autres devinent (titre/artiste, qui l'a ajouté, ou mixte).
  Nécessite ≥ 3 joueurs **dont 2 réels** (un bot ne peut pas être DJ). Récap des
  titres + liens en fin de partie.
- **Mixte** (défaut) — séquence mélangée de manches, par sous-modes au choix.

Filtre par catégories, durée et nombre de manches réglables, et **bots** (niveau
réglable) pour compléter une partie.

## Back-office quiz

Page protégée `/admin` pour écrire des questions manuelles (QCM, vrai/faux,
réponse libre, image), choisir leur langue et les activer/désactiver. Définir
`ADMIN_TOKEN` dans `apps/server/.env` et une `DATABASE_URL` valide. Le jeton est
demandé à la connexion sur `/admin`.

## Déploiement (Dokploy)

La stack de prod est décrite dans
[`docker-compose.prod.yml`](./docker-compose.prod.yml) : `postgres`, `server`
(Bun) et `web` (build statique servi par nginx). Voir
[`.env.production.example`](./.env.production.example) pour les variables.

1. **Dokploy → Create → Compose**, pointant sur ce repo et `docker-compose.prod.yml`.
2. Renseigner les variables d'environnement : `POSTGRES_PASSWORD`, `ADMIN_TOKEN`,
   `CORS_ORIGINS` (domaine du client), `VITE_SERVER_URL` (URL publique du serveur).
3. Assigner les **domaines** via Traefik : le service `web` (port 80) sur le
   domaine principal, le service `server` (port 3001) sur le sous-domaine d'API.
   `VITE_SERVER_URL` doit pointer vers ce domaine d'API, et `CORS_ORIGINS` vers
   celui du client.
4. Déployer. Les **migrations** s'appliquent automatiquement au démarrage du
   serveur. Pour peupler le contenu (one-shot) :
   `docker compose -f docker-compose.prod.yml exec server bun run db:seed`.

Les images uploadées sont persistées dans le volume `uploads`, la base dans
`pgdata`.

> Test local de la stack de prod :
> `docker compose -f docker-compose.prod.yml up --build` (après avoir copié
> `.env.production.example` en `.env`).

## Versionnement & gitflow

- Branches : `main` (production, taguée), `dev` (intégration), `feature/*`,
  `release/*`.
- Une **release** se coupe depuis `dev` (`release/x.y.z`), y reçoit le bump de
  version + le CHANGELOG, puis fusionne dans `main` (taguée `vX.Y.Z`) et revient
  dans `dev`. Voir [`CHANGELOG.md`](./CHANGELOG.md). Versionnage [SemVer](https://semver.org).