Introduction au Projet

Bienvenue dans la documentation de CyberCity. Ce projet est une application multi-plateforme complète permettant de créer, gérer et jouer à des jeux de plateau en temps réel. L'application est construite sur une architecture client-serveur moderne, utilisant Angular pour le frontend web, Flutter pour l'application mobile, et Node.js avec TypeScript pour le backend.

Architecture Globale

L'application est divisée en trois parties principales qui communiquent entre elles :

Client Web (Frontend)

• Développé avec Angular
• Interface utilisateur interactive et réactive
• Communication en temps réel via Socket.IO
• Animations et transitions fluides entre les différentes vues
• Support multilingue (Français/Anglais)
• Système d'authentification Firebase

Client Mobile

• Développé avec Flutter
• Architecture Clean (Domain/Data/Presentation)
• Support multi-plateforme (iOS, Android, Web)
• Intégration Firebase Authentication
• Communication Socket.IO pour le temps réel
• Interface utilisateur native et responsive

Serveur (Backend)

• Développé avec Node.js et TypeScript
• Architecture orientée services avec injection de dépendances (TypeDI)
• Communication en temps réel via Socket.IO
• Persistance des données avec MongoDB
• Logique de jeu complexe (déplacement, combat, IA)
• Authentification Firebase Admin SDK
• Gestion de sessions utilisateur
• Système de monnaie virtuelle et prize pool

Flux de données et Communication

La communication entre les clients et le serveur se fait principalement de trois manières :

1. API REST : Utilisée pour les opérations CRUD et l'authentification

   • Endpoints exposés par les contrôleurs (GameManagerController, AuthController, UserController, FriendsController, ChannelController, AvatarController)
   • Utilisée pour la gestion administrative des jeux et des comptes utilisateurs

2. WebSockets (Socket.IO) : Communication bidirectionnelle en temps réel

   • Utilisée pour toutes les interactions de jeu (déplacements, combats, chat)
   • Mise à jour instantanée de l'état du jeu pour tous les joueurs
   • Système d'événements et de salles pour isoler les communications par partie
   • Notifications en temps réel (demandes d'amis, messages de chat)

3. Firebase Authentication : Système d'authentification centralisé

   • Authentification email/mot de passe
   • Vérification des tokens ID
   • Gestion des sessions utilisateur

Le diagramme (à venir tkt ...) suivant illustre le flux typique d'une partie :

1. Le joueur s'authentifie via Firebase (web ou mobile)
2. Le système crée une session et authentifie le socket
3. Il crée une partie ou rejoint une partie existante via un code ou depuis la liste publique
4. Les joueurs se retrouvent dans une salle d'attente
5. La partie commence, le serveur gère l'état du jeu et les tours
6. Les joueurs interagissent via l'interface, envoyant des commandes au serveur
7. Le serveur traite les commandes, met à jour l'état du jeu et diffuse les mises à jour
8. À la fin de la partie, les prix en monnaie virtuelle sont distribués et les statistiques sont affichées

Organisation de la Documentation

La documentation est organisée en quatre sections principales pour faciliter la navigation et la compréhension du projet :

1. Documentation Principale (Vous êtes ici)

• Vue d'ensemble du projet
• Architecture globale
• Organisation de la documentation
• Guide de démarrage

2. Documentation Coté Client

La documentation côté client web est organisée par pages et fonctionnalités principales :

• Pages : Documentation détaillée des 11 principales pages de l'application
  • Page d'Authentification
  • Page d'Accueil
  • Administration des Jeux
  • Édition de Jeu
  • Création de Partie
  • Page de Rejoindre
  • Création de Personnage
  • Salle d'Attente
  • Vue de Jeu
  • Statistiques
  • Application Principale
• Services et Composants : Explications des services et composants réutilisables
  • Services de communication avec le serveur
  • Service d'authentification Firebase
  • Service de gestion des utilisateurs
  • Service de gestion des amis
  • Service d'internationalisation
  • Composants d'interface utilisateur
  • Gestion des états et animations

3. Documentation Coté Serveur

La documentation côté serveur est organisée par domaines fonctionnels :

• Infrastructure et Configuration : Mise en place du serveur
• Authentification et Gestion des Sessions : Firebase, sessions, middleware
• Gestion des WebSockets : Communication en temps réel
• Gestion des Utilisateurs : Profils, avatars, monnaie virtuelle
• Système d'Amis : Demandes, notifications en temps réel
• Système de Canaux : Channels de chat publics/privés
• Gestion des Parties : Logique de jeu principale
• Système de Combat : Mécanique des combats
• Gestion des Items : Objets et interactions
• Gestion des Joueurs : Joueurs humains et IA
• Système de Prize Pool : Monnaie virtuelle et récompenses
• Contrôle de Jeu et Vérification : Validation et règles
• Système du Chatbox : Communication entre joueurs
• Système de Traduction : Support multilingue
• Classes du Jeu : Structures de données principales

4. Documentation Mobile

La documentation de l'application mobile est organisée par pages et fonctionnalités principales :

• Pages : Documentation détaillée des 10 principales pages de l'application mobile
  • Page d'Authentification
  • Page d'Accueil
  • Création de Partie
  • Page de Rejoindre
  • Création de Personnage
  • Salle d'Attente
  • Vue de Jeu
  • Statistiques
  • Boutique
  • Aide
• Architecture et Services : Explications de l'architecture Clean et des composants
  • Architecture Clean en trois couches
  • Injection de dépendances (GetIt)
  • Gestion d'état (Riverpod)
  • Communication avec le serveur (HTTP et Socket.IO)
  • Fonctionnalités transversales (Core)

Par où commencer ?

Si vous découvrez ce projet :

1. Pour comprendre la structure globale :

   • Commencez par cette page principale pour avoir une vue d'ensemble
   • Consultez la section "Application Principale" dans la documentation client et "Infrastructure et Configuration" dans la documentation serveur

2. Pour comprendre le système d'authentification :

   • Explorez la "Page d'Authentification" dans la documentation client
   • Consultez "Authentification et Gestion des Sessions" dans la documentation serveur
   • Regardez le module "Authentification" dans la documentation mobile

3. Pour comprendre le flux utilisateur :

   • Explorez les pages dans l'ordre d'utilisation typique :
     • Page d'Authentification → Page d'Accueil → Création de Partie / Rejoindre → Création de Personnage → Salle d'Attente → Vue de Jeu → Statistiques

4. Pour comprendre la logique du jeu :

   • Consultez la section "Gestion des Parties" dans la documentation serveur
   • Puis explorez le "Système de Combat" et la "Gestion des Joueurs"

5. Pour comprendre l'interaction en temps réel :

   • Consultez la section "Gestion des WebSockets" dans la documentation serveur
   • Puis explorez les services de communication dans la documentation client et mobile

6. Pour comprendre le système social :

   • Consultez "Système d'Amis" et "Système de Canaux" dans la documentation serveur
   • Explorez les services correspondants dans les documentations client et mobile

Entités Principales du Jeu

Pour mieux comprendre le domaine du jeu, voici les principales entités et leurs relations :

• User : Informations utilisateur (Firebase UID, username, avatar, monnaie virtuelle, amis)
• Session : Session active d'un utilisateur connecté
• Game : Définition d'un jeu (grille, mode, taille)
• OnGoingGame : État d'une partie en cours (inclut prize pool, visibilité, drop-in/out)
• Player : Informations sur un joueur dans une partie
• Bot : Extension de Player pour les IA (défensives et agressives)
• Combat : État d'un combat entre joueurs
• Cell : Cellule de la grille de jeu
• Item : Objets que les joueurs peuvent collecter
• Channel : Canal de chat avec messages et participants
• ChatMessage : Message dans un canal
• Avatar : Image de profil personnalisée d'un utilisateur

Fonctionnalités Principales

Authentification et Comptes Utilisateur

• Système complet d'authentification avec Firebase
• Création de compte avec email/mot de passe
• Connexion avec username ou email
• Gestion de session (un seul appareil à la fois)
• Avatar personnalisé téléchargeable

Système Social

• Liste d'amis avec recherche d'utilisateurs
• Demandes d'amis en temps réel
• Notifications Socket.IO pour les événements sociaux
• Canaux de chat publics et privés
• Chat global et par canal

Économie Virtuelle

• Monnaie virtuelle par utilisateur
• Frais d'entrée pour les parties
• Prize pool distribué aux gagnants
• Remboursements automatiques

Internationalisation

• Support complet Français/Anglais
• Traductions côté client et serveur
• Sélecteur de langue dans l'interface
• Fichiers de traduction JSON partagés

Application Mobile

• Application Flutter multi-plateforme
• Architecture Clean pour la maintenabilité
• Authentification et gestion de profil
• Liste des jeux et création de partie
• Chat et système de canaux

Améliorations du Gameplay

• Page dédiée pour rejoindre une partie
• Liste publique des parties disponibles
• Parties "drop-in/drop-out" (rejoindre en cours de jeu)
• Visibilité des parties (publique/amis)
• Verrouillage de partie
• Affichage des codes d'accès

Sécurité

• Guards pour la protection des routes
• Middleware d'authentification
• Validation des sessions
• Vérification des tokens Firebase