From 43b68d1352e5d4b3e3d08971b5a3790efa961798 Mon Sep 17 00:00:00 2001
From: Maxiwere45 <amdjad9857@gmail.com>
Date: Tue, 9 Jun 2026 15:24:33 +0200
Subject: [PATCH] docs: update architecture documentation for new layered
 design

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md | 49 +++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2508680..8b68a3e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -2,31 +2,42 @@
 
 ## Overview
 
-The application follows a modular structure separated by responsibilities (models, pages, components, services).
+L'application suit une **Clean Architecture allégée** en trois couches, avec une règle de
+dépendance stricte : les dépendances pointent vers l'intérieur. Le state management est assuré
+par Riverpod (providers manuels).
 
-## Layers
+## Couches
 
-### 1. Data Layer
+### domain (Dart pur)
+- **Entités** : `Pokemon`, immuable, sans dépendance Flutter/DB/API.
+- **Repository (interface)** : `PokemonRepository` définit le contrat d'accès aux données.
+- **Jeu** : `GameState` (état immuable) et `GameEngine` (règles pures, testables).
 
-- **Models**: `Pokemon` class defines the data structure for a Pokemon, including serialization/deserialization logic.
-- **API**: `PokemonApi` handles communication with the Tyradex REST API using the `http` package.
-- **Database**: `PokedexDatabase` manages local persistence using SQLite (`sqflite`). It uses batch operations for performance during initial sync.
+### data
+- **DTO** : `PokemonDto` centralise tout le parsing JSON (API Tyradex + SQLite).
+- **Datasources** : `PokemonLocalDataSource` (SQLite via sqflite), `PokemonRemoteDataSource` (HTTP).
+- **Repository (impl)** : `PokemonRepositoryImpl` applique « DB locale d'abord, sinon API + cache ».
+  Sur le web, le datasource local est absent (`null`).
 
-### 2. Business Logic & State
+### presentation
+- **Providers** : `pokemonRepositoryProvider` (DI), `pokedexProvider` (`AsyncNotifier`),
+  `gameProvider` (`Notifier<GameState>`), `selectedTabProvider` (onglet courant).
+- **Pages** : `ConsumerWidget` / `ConsumerStatefulWidget` qui observent les providers.
+- **Widgets** : éléments réutilisables (`PokemonImage`, `PokemonTile`, `PokemonTypeWidget`).
+- **Thème** : `type_colors.dart` (couleur/format des types).
 
-- **State Management**: Uses Flutter's `StatefulWidget` and `setState` for local page state.
-- **Reactivity**: `ValueNotifier` in the database layer notifies the UI when data changes (e.g., catching a Pokemon updates the list).
-- **Persistence**: `shared_preferences` is used for simple key-value storage like best scores.
+## Flux de données
 
-### 3. UI Layer
+```
+UI (Consumer) → Notifier → GameEngine (règles) + Repository (données)
+                                 → DataSource (SQLite / HTTP) → DTO → Entity
+```
 
-- **Pages**: Top-level screens like `MainPage`, `PokemonListPage`, and `GuessPage`.
-- **Components**: Reusable UI elements like `PokemonTile`.
-- **Navigation**: Managed in `MainPage` using `IndexedStack` to preserve tab state across navigation.
+Riverpod re-render automatiquement les consommateurs concernés. Plus de bus d'événements global
+ni d'accès inter-pages via l'arbre de widgets.
 
-## Data Flow
+## Tests
 
-1. At startup, the app checks the local database.
-2. If the database is missing generations, it fetches the full list from Tyradex API and performs a batch insert.
-3. User interactions (like a correct guess) update the local database.
-4. The database triggers a notification, causing relevant UI components to refresh their view.
+- `test/domain/game_engine_test.dart` : règles du jeu.
+- `test/data/pokemon_dto_test.dart` : parsing.
+- `test/data/pokemon_repository_test.dart` : logique du repository (datasources factices).