ayoub/nerdware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nerdware/ARCHITECTURE.md

15 KiB
Raw Blame History

NerdWare — Architecture

Party game web multi-épreuves centré culture geek (jeux vidéo, manga, pop culture), ambiance WarioWare (rythme rapide, fun, transitions punchy). Packages du monorepo : @nerdware/shared, @nerdware/server, @nerdware/client. V1 : Blindtest (YouTube) + Quiz culture. Pensé pour s'étendre (GeoGuessr-like, etc.).

1. Principes directeurs

  • Web app, chacun sur son PC. Pas d'écran central / pas d'hôte spécial pour l'affichage. Chaque joueur voit tout (titre en cours, choix, scoreboard) synchronisé en temps réel.
  • Serveur source de vérité. Le timer, les scores, l'ordre des manches, le tirage du DJ : tout est tranché côté serveur. Les clients n'affichent qu'un état reçu. Jamais confiance au client (triche / désync).
  • Moteur de jeu générique. Chaque épreuve implémente la même interface (start / submitAnswer / reveal / score). Brancher une nouvelle épreuve = écrire un module, pas retoucher la plomberie.
  • Audio joué localement par chaque client, mais piloté centralement (le DJ broadcast play/pause/seek, les autres se recalent).

2. Stack technique

Couche Choix Notes
Langage TypeScript (front + back) Types partagés des events WS → désync = erreur de compile
Backend HTTP Fastify OAuth YouTube, back-office quiz, health checks
Temps réel Socket.IO Cœur du système : rooms natives, reconnexion auto, acks
Game loop Node + autorité serveur Timer, scores, tirage DJ tranchés serveur
État des rooms En mémoire (Map) Suffisant pour jouer entre potes
Persistance contenu PostgreSQL (instance partagée) + Drizzle ORM Questions de quiz, catégories, historiques
Audio YouTube IFrame Player API Gratuit, pas de Premium requis
Front build Vite + React SPA, pas de SSR (jeu derrière un lobby)
Routing wouter ~2 ko ; 3-4 routes triviales, pas besoin de plus
État client Zustand Reflète l'état poussé par Socket.IO
Données HTTP TanStack Query UNIQUEMENT back-office quiz + auth (pas le jeu temps réel)
UI Tailwind + shadcn/ui Contrôle total du style pour l'ambiance WarioWare
Animations Framer Motion Transitions de manche, reveal, scores, countdown — le "fun"
(Optionnel) Redis Seulement pour survivre à un redémarrage serveur

Pourquoi YouTube plutôt que Spotify

  • Pas de compte Premium requis ; lecture dans n'importe quel navigateur.
  • Synchro gérable via seekTo(seconds) + events de buffering.
  • Recherche/soumission par URL ou API Data v3.
  • Export Spotify en bonus post-game : on stocke titre + artiste, et en fin de partie on génère des liens de recherche / une playlist.
  • ⚠️ Piège : certaines vidéos ont l'embedding désactivé → détecter à la soumission, prévoir un fallback.

3. Schéma de données

Persistant (PostgreSQL)

quiz_category
  id            uuid pk
  name          text
  created_at    timestamptz

quiz_question
  id              uuid pk
  category_id     uuid fk -> quiz_category
  format          text         -- 'mcq' | 'truefalse' | 'free' | 'image_reveal'
  prompt          text
  difficulty      int          -- 1..3
  source          text         -- 'opentdb' | 'manual'
  -- champs selon le format (NULL si non applicable) :
  choices         jsonb        -- mcq/truefalse : ["A","B","C","D"]
  correct_index   int          -- mcq/truefalse : index de la bonne réponse
  accepted_answers jsonb       -- free : ["Jupiter","planète Jupiter", ...] (matching tolérant)
  image_url       text         -- image_reveal : image à dévoiler
  created_at      timestamptz

quiz_played             -- anti-répétition : ce qui a déjà été joué
  question_id   uuid fk -> quiz_question
  room_code     text         -- ou un identifiant de groupe de potes
  played_at     timestamptz

game_history            -- optionnel, pour stats / portfolio
  id            uuid pk
  room_code     text
  played_at     timestamptz
  modes         jsonb        -- épreuves jouées
  results       jsonb        -- scores finaux par joueur

Le blindtest n'a pas besoin de DB : les titres sont soumis en session, vivent le temps de la partie.

Éphémère (en mémoire, par room)

Room
  code            string          -- code de jointure (ex: "RTKP")
  status          'lobby' | 'in_round' | 'reveal' | 'scores' | 'ended'
  players         Map<playerId, Player>
  settings        RoomSettings
  rounds          Round[]         -- planifiés
  currentRound    int
  scores          Map<playerId, number>

Player
  id              string
  name            string
  connected       bool
  socketId        string

RoomSettings
  blindtestMode   'title_artist' | 'who_added' | 'mixed'
  roundDuration   int             -- secondes (def. 60)
  rounds          RoundConfig[]   -- séquence d'épreuves

Round (état runtime)
  type            'blindtest' | 'quiz'
  djId            string | null   -- blindtest only, joueur neutre
  payload         object          -- dépend du type (voir §5)
  votes           Map<playerId, Vote>
  startedAt       number          -- timestamp serveur
  endsAt          number          -- startedAt + duration

4. Interface du game loop générique

Chaque épreuve implémente ce contrat. Le moteur ne connaît que cette interface.

interface GameRound {
  type: string;

  // Prépare la manche : tire le DJ si besoin, choisit le contenu,
  // renvoie le payload à broadcaster (sans la réponse !).
  start(room: Room): RoundStartPayload;

  // Enregistre/valide le vote d'un joueur. Idempotent.
  submitAnswer(room: Room, playerId: string, answer: Answer): void;

  // Calcule la bonne réponse + détail à révéler à tous.
  reveal(room: Room): RevealPayload;

  // Met à jour room.scores selon les votes vs la vérité.
  score(room: Room): ScoreDelta[];
}

Boucle d'orchestration (serveur) :

lobby
  → pour chaque RoundConfig dans settings.rounds :
      round.start()            → broadcast ROUND_START (payload sans réponse)
      [timer serveur lancé]
      ... submitAnswer() au fil des votes ...
      fin = (timer écoulé) OU (tous ont voté)
      round.reveal()           → broadcast ROUND_REVEAL
      round.score()            → broadcast SCORE_UPDATE
  → broadcast GAME_END (scores finaux + export Spotify éventuel)

Règle de fin de manche : la première des deux conditions — endsAt atteint ou tous les joueurs éligibles ont voté — déclenche le reveal. Le DJ, s'il y en a un, compte comme votant éligible.

5. Events WebSocket

Convention : CLIENT → SERVER et SERVER → CLIENT. Tout timestamp est serveur.

Connexion / lobby

Event Sens Payload
room:create C→S { playerName } → renvoie { roomCode, playerId }
room:join C→S { roomCode, playerName }
room:state S→C snapshot complet de la room (à chaque changement)
lobby:updateSettings C→S { blindtestMode, roundDuration, rounds }
player:left / player:rejoined S→C { playerId }

Soumission blindtest (phase pré-partie)

Event Sens Payload
blindtest:submitTrack C→S { youtubeUrl } — privé, jamais rebroadcast tel quel
blindtest:submitOk S→C { accepted, reason? } (vérifie embedding autorisé)

Déroulé d'une manche

Event Sens Payload
round:start S→C { type, djId?, endsAt, payload } (payload SANS la réponse)
media:control C→S `{ action: 'play'
media:sync S→C { action, positionSec, atServerTs } → les clients se recalent
round:vote C→S { answer } (selon le mode, voir ci-dessous)
round:voteAck S→C { count, total } — progression anonyme
round:reveal S→C { truth, perPlayerResult }
score:update S→C { scores }
game:end S→C { finalScores, spotifyExport? }

Forme du vote selon blindtestMode

  • title_artist → { title, artist } (texte libre, matching tolérant).
  • who_added → { guessedPlayerId }.
  • mixed → { title, artist, guessedPlayerId } (points séparés).

6. Flow détaillé — Blindtest

PHASE 1 — Soumission (lobby)
  Chaque joueur envoie N titres (youtubeUrl) en privé.
  Serveur vérifie l'embedding, stocke { trackId, submittedBy, url }.
  Les titres sont mélangés ; submittedBy reste secret.

PHASE 2 — Manche (répétée par titre)
  start():
    - tire un DJ NEUTRE = joueur != submittedBy de ce titre
      (si impossible, re-tire ; jamais le contributeur)
    - payload = { trackId, youtubeId } SANS submittedBy ni réponse
    - broadcast round:start (+ endsAt = now + roundDuration)
  pendant la manche :
    - DJ envoie media:control (play/pause/seek)
    - serveur rebroadcast media:sync à tous → recalage
    - chaque joueur (DJ INCLUS, à l'aveugle) envoie round:vote
      → le DJ vote comme les autres pour ne pas perdre de points ;
        il n'a aucun avantage (mode who_added : il n'est pas le
        contributeur ; mode title_artist : il ne connaît pas plus
        la réponse).
  fin : timer écoulé OU tous votés
  reveal():
    - dévoile titre, artiste, ET submittedBy
  score():
    - title_artist : points si match titre/artiste (tolérance fuzzy)
    - who_added    : points si guessedPlayerId == submittedBy
    - mixed         : addition des deux barèmes

PHASE 3 — Fin de partie
  Génère l'export : liens de recherche Spotify (ou playlist via API)
  à partir des { title, artist } révélés.

Point d'attention — asymétrie d'attention du DJ : il gère la lecture pendant que les autres se concentrent sur leur réponse. Sur 60 s c'est négligeable. Option non prioritaire : laisser le vote du DJ ouvert ~5 s de plus. À ne pas sur-ingénierer en v1.

7. Flow détaillé — Quiz culture

Le quiz n'a pas de DJ. Une question = une manche. Quatre formats partagent le même cycle start → vote → reveal → score, seul le payload et le barème changent.

7.1 Sources de contenu (V1)

Source Formats fournis Rôle
Open Trivia DB mcq, truefalse Seed automatique de la banque. Gratuit, réponses déjà validées. Tokens de session pour éviter la répétition. (EN → traduisible en FR au seed.)
Manuel (back-office) free, image_reveal (+ mcq/truefalse maison) Écrit par nous. Apporte le FR, l'actu, le ton perso/private jokes. Vérifié par construction.

Pas d'IA en V1 → pas de problème de vérification. Open Trivia est pré-validé ; le manuel est écrit par nous. Génération IA = piste optionnelle plus tard si la saisie manuelle lasse.

Anti-répétition : à chaque question jouée, on insère dans quiz_played. La sélection exclut ce qui a déjà été vu par le groupe → la banque grossit, les répétitions disparaissent.

7.2 Les quatre formats

COMMUN à tous :
  start():  pioche une question NON déjà jouée (quiz_played), payload SANS la réponse
  fin:      timer écoulé OU tous votés
  reveal(): dévoile la bonne réponse + qui a eu juste
  score():  barème selon le format (+ bonus rapidité ∝ temps restant)

── mcq ──────────────────────────────────
  payload : { prompt, choices }              (sans correct_index)
  vote    : { choiceIndex }
  score   : juste si choiceIndex == correct_index

── truefalse ────────────────────────────
  identique à mcq avec choices = ["Vrai","Faux"]

── free (réponse libre) ──────────────────
  payload : { prompt }
  vote    : { text }
  score   : matching TOLÉRANT contre accepted_answers
            (normalisation : minuscules, accents, espaces ;
             distance de Levenshtein pour les fautes de frappe)

── image_reveal (image qui se dévoile) ──
  payload : { imageUrl, revealSchedule }
  mécanisme : l'image se révèle progressivement (flou qui diminue
              ou masque qui se lève) par paliers pilotés par le
              timer SERVEUR. Le client n'affiche que l'état reçu.
  vote    : { text }  — on peut répondre à tout moment
  score   : DÉGRESSIF — plus on trouve tôt (image encore floue),
            plus on marque. Le palier atteint au moment du vote
            détermine les points. Matching tolérant comme `free`.

7.3 Image progressive — stockage & révélation

Stockage (V1) : volume Docker monté + servi en statique par Fastify. Upload via le back-office ; image_url en DB pointe vers le chemin servi. Simple, ~0 RAM, large pour quelques centaines d'images sur 100 Go de disque.

MinIO / stockage objet écarté : surdimensionné pour ce volume (RAM + service à maintenir pour un jeu entre potes). À reconsidérer seulement comme stockage mutualisé pour tout le homelab — décision infra transverse, pas de ce projet.

Révélation : mécanisme front (flou CSS décroissant, ou tuiles qui se découvrent) cadencé par le serveur : le serveur émet les paliers (reveal:step) pour que tous voient le même niveau de flou au même instant. Le score retenu = palier actif côté serveur à la réception du vote (jamais le client qui décide → non truquable sur le scoring).

Anti-triche sur l'image — deux niveaux :

  • V1 (simple, suffisant entre potes) : image complète envoyée, flou appliqué en CSS. Trichable via devtools par quelqu'un de motivé, mais l'auto-régulation sociale suffit. Le scoring reste serveur-autoritaire malgré tout.
  • Plus tard (robuste) : le serveur pré-génère les paliers avec sharp (versions floutées/pixelisées) et n'envoie que le palier courant — l'image nette n'atteint jamais le client avant le reveal. À coder seulement si la triche devient un vrai sujet.

7.4 Back-office de saisie (manuel)

Formulaire simple écrivant dans quiz_question :

  • choix du format, prompt, category, difficulty
  • free → liste de réponses acceptées
  • image_reveal → upload image + ordre de révélation
  • mcq/truefalse → choix + bonne réponse

Rien de lourd : une page protégée suffit pour la V1.

8. Extensibilité (post-V1)

Ajouter une épreuve = implémenter GameRound + définir son payload et son vote. Exemples :

  • GeoGuessr-like : payload = coords / Street View embed ; vote = position devinée ; score = distance.
  • Mini-épreuves rapides type "réflexe culture" qui collent au tempo WarioWare.

Le reste (timer serveur, rooms, scoreboard, sync, lobby) est mutualisé et ne bouge pas.

9. Notes de déploiement (infra perso)

  • Cible : VPS Hostinger KVM 2 — 2 vCPU, 8 Go RAM, 100 Go. Large pour ce jeu (Node + WebSocket + Postgres partagée restent légers).
  • Conteneurisable via Docker → déployable sur Dokploy.
  • WebSocket : s'assurer que le reverse proxy passe bien l'upgrade Connection: upgrade.
  • OAuth / clés API (YouTube Data, Spotify export) en variables d'environnement, jamais en dur.
  • HTTPS via le domaine existant → redirect URIs OAuth valides.
  • Le seed Open Trivia DB : script one-shot au déploiement (respecter la limite 1 req / 5 s).