Documentation Application Mobile

L'application mobile de CyberCity est développée avec Flutter, permettant un déploiement sur iOS, Android, et Web. Elle suit une architecture Clean en trois couches (Presentation, Domain, Data) pour assurer la maintenabilité, la testabilité et la séparation des responsabilités. Cette documentation présente la structure et le fonctionnement de l'application mobile selon une approche technique, organisée autour des principales pages.

Architecture Générale

L'application mobile utilise une architecture Clean Architecture avec injection de dépendances via GetIt et gestion d'état avec Riverpod. Cette architecture garantit:

Technologies utilisées

Framework et langages

Communication

UI/UX

Structure de l'application

L'application est composée de:

Pages de l'Application

Toutes les pages sont des ConsumerStatefulWidget qui écoutent et réagissent aux changements d'état via Riverpod.

0. Page d'Authentification (AuthPage)

Type : ConsumerStatefulWidget
Chemin : features/auth/presentation/pages/auth_page.dart

Fonctionnalité : Point d'entrée de l'application permettant la connexion et l'inscription via Firebase Authentication.

Providers principaux :

Composants clés :

Use Cases :

Navigation : HomePage (après connexion)

1. Page d'Accueil (HomePage)

Type : ConsumerStatefulWidget
Chemin : features/home/presentation/pages/home_page.dart

Fonctionnalité : Hub central post-authentification avec accès aux fonctionnalités principales.

Providers principaux :

Composants clés :

Fonctionnalités :

Navigation : JoinPage, GameCreationPage, ShopPage, HelpPage

2. Création de Partie (GameCreationPage)

Type : ConsumerStatefulWidget
Chemin : features/game/presentation/pages/game_creation_page.dart

Fonctionnalité : Sélection d'un jeu et configuration des paramètres de partie.

Providers principaux :

Composants clés :

Paramètres configurables :

Écouteurs Socket.IO :

Navigation : CharacterCreationPage (mode "create")

3. Page de Rejoindre (JoinPage)

Type : ConsumerStatefulWidget
Chemin : features/game/presentation/pages/join_page.dart

Fonctionnalité : Liste des parties publiques disponibles et rejoindre via code.

Providers principaux :

Composants clés :

Fonctionnalités :

Écouteurs Socket.IO :

Navigation : CharacterCreationPage (mode "join"), GameViewPage (drop-in)

4. Création de Personnage (CharacterCreationPage)

Type : ConsumerStatefulWidget
Chemin : features/game/presentation/pages/character_creation_page.dart

Fonctionnalité : Choix d'avatar et de nom de personnage.

Providers principaux :

Composants clés :

Validations :

Limites de joueurs :

Écouteurs Socket.IO :

Navigation : WaitingRoomPage

5. Salle d'Attente (WaitingRoomPage)

Type : ConsumerStatefulWidget
Chemin : features/game/presentation/pages/waiting_room_page.dart

Fonctionnalité : Attente des joueurs et lancement de la partie (hôte).

Providers principaux :

Composants clés :

Fonctionnalités hôte :

Écouteurs Socket.IO :

Navigation : GameViewPage (démarrage), HomePage (quitter/expulsé/annulé)

6. Vue de Jeu (GameViewPage)

Type : ConsumerStatefulWidget with WidgetsBindingObserver
Chemin : features/game/presentation/pages/game_view_page.dart

Fonctionnalité : Interface de jeu en temps réel avec grille, commandes et inventaire.

Providers principaux :

Composants clés :

Écouteurs Socket.IO (via GameViewNotifier) :

Lifecycle management :

Navigation : StatsPage (fin de partie), HomePage (quitter/déconnecté)

7. Statistiques (StatsPage)

Type : ConsumerStatefulWidget with WidgetsBindingObserver
Chemin : features/stats/presentation/pages/stats_page.dart

Fonctionnalité : Affichage des résultats et statistiques post-partie.

Providers principaux :

Composants clés :

Données affichées :

Écouteurs Socket.IO :

Lifecycle management :

Navigation : HomePage (quitter)

8. Boutique (ShopPage)

Type : ConsumerStatefulWidget
Chemin : features/shop/presentation/pages/shop_page.dart

Fonctionnalité : Achat d'éléments cosmétiques avec monnaie virtuelle.

Providers principaux :

Composants clés :

Fonctionnalités :

Use Cases :

Articles : 7 items (avatars, profils de différentes raretés)

Navigation : HomePage (retour), HelpPage (aide complète)

9. Aide (HelpPage)

Type : ConsumerStatefulWidget
Chemin : features/help/presentation/pages/help_page.dart

Fonctionnalité : Documentation complète de l'application en deux panneaux.

Providers principaux :

Composants clés :

Sections (16 au total) :

Style :

Navigation : HomePage (retour)

Architecture Clean

Couche Presentation

Technologies : Flutter, Riverpod

Responsabilités :

Pattern : MVVM avec Riverpod

Couche Domain

Technologies : Dart pur (indépendant de Flutter)

Responsabilités :

Principe : Dependency Inversion (les détails dépendent des abstractions)

Couche Data

Technologies : Dio (HTTP), Socket.IO, Firebase

Responsabilités :

Pattern : Repository pattern

Gestion d'État (Riverpod)

Types de providers utilisés

StateNotifierProvider

Pour l'état mutable avec logique business :

StateNotifierProvider<AuthNotifier, AuthState>
StateNotifierProvider<GameViewNotifier, GameViewState>

Provider

Pour les dépendances et services :

Provider<TranslationWrapper>
Provider<SocketService>

FutureProvider / StreamProvider

Pour les données asynchrones

Pattern de state

Tous les states utilisent copyWith pour l'immutabilité :

class AuthState {
  final bool isLoading;
  final String? errorMessage;
  
  AuthState copyWith({bool? isLoading, String? errorMessage}) { ... }
}

Communication Serveur

Service : SocketService (singleton)

Connexion :

Events principaux :

Pattern :

socket.on('eventName', (data) => { ... });
socket.emit('eventName', data);

HTTP/REST

Service : Dio avec intercepteurs

Endpoints :

Pattern :

final response = await dio.get('/endpoint', 
  options: Options(headers: {'Authorization': 'Bearer $token'}));

Firebase

Services utilisés :

Internationalisation (i18n)

Langues : Français, English

Service : TranslationService

Provider : translationProvider

Usage :

ref.watch(translationProvider).translate('AUTH_PAGE.SIGN_IN')

Fichiers : JSON avec clés hiérarchiques

Thèmes

Thèmes disponibles :

Provider : themeNotifierProvider<ThemeNotifier, ThemeState>

Personnalisation :

Navigation

Router : GoRouter (go_router package)

Routes : Définies dans AppRoutes

Navigation :

context.go(AppRoutes.home.path)
context.go(AppRoutes.gameView.path, extra: {...})

Paramètres : Passés via extra ou query params

Widgets Réutilisables

Widgets communs

Widgets de jeu

Widgets de boutique

Widgets d'aide

Services

SocketService

Gestion de la connexion Socket.IO (singleton)

AssetPreloaderService

Préchargement des assets de jeu (sprites, images)

TranslationService

Traductions multilingues

HelpService

Contenu d'aide contextuel par route

Dépendances principales

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.x
  go_router: ^14.x
  socket_io_client: ^2.x
  firebase_auth: ^5.x
  firebase_storage: ^12.x
  dio: ^5.x
  flutter_svg: ^2.x
  flutter_markdown: ^0.7.x
  get_it: ^7.x
  font_awesome_flutter: ^10.x

Points clés de l'architecture

  1. Séparation des responsabilités : Clean Architecture en 3 couches
  2. Gestion d'état réactive : Riverpod avec StateNotifier
  3. Communication temps réel : Socket.IO avec reconnexion automatique
  4. Internationalisation : Support FR/EN complet
  5. Thèmes : 2 thèmes cyberpunk personnalisés
  6. Navigation : GoRouter avec paramètres typés
  7. Lifecycle : Gestion de l'état de l'app (background/foreground)
  8. Performance : Préchargement, cache d'images
  9. UX : Popups, animations, feedback utilisateur
  10. Maintenabilité : Code modulaire, widgets réutilisables