# Application Architecture

## Overview

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).

## Couches

### core (transversal)

- **`AppConstants`** : toutes les constantes métier en un seul endroit (vies, points, shiny odds,
  plages de générations, clés SharedPreferences, URL API).
- **`logger`** : wrapper minimal autour de `dart:developer`.

### 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).
  - `GameEngine` gère : soumission de réponse, vies, hints, skips, score, Shiny, bonus périodiques.
  - `GameStatus` : `loading | playing | roundWon | gameOver`.
  - `GuessResult` : `correct | wrong | gameOver | invalid`.

### data

- **DTO** : `PokemonDto` centralise tout le parsing JSON (API Tyradex + SQLite).
  - `fromTyradexJson()`, `fromDb()`, `toDb()`.
- **Datasources** :
  - `PokemonLocalDataSource` — SQLite via sqflite ; absent (`null`) sur le web.
  - `PokemonRemoteDataSource` — HTTP vers Tyradex + PokéAPI (genus anglais).
- **Repository (impl)** : `PokemonRepositoryImpl` applique « DB locale d'abord, sinon API + cache ».

### l10n

Internationalisation complète **FR / EN** via `flutter_localizations` + `intl`.
Fichiers générés : `app_localizations.dart`, `app_localizations_fr.dart`, `app_localizations_en.dart`.
La langue active est persistée dans SharedPreferences (`AppConstants.prefsLocale`).

### presentation

#### Providers (Riverpod)

| Provider | Type | Rôle |
| --- | --- | --- |
| `pokemonRepositoryProvider` | `Provider` | DI du repository |
| `pokedexProvider` | `AsyncNotifier<List<Pokemon>>` | Chargement + cache du Pokédex |
| `gameProvider` | `Notifier<GameState>` | État de la partie en cours |
| `selectedTabProvider` | `StateProvider<int>` | Onglet de navigation courant |
| `localeProvider` | `Notifier<Locale>` | Langue active (FR/EN) + persistance |
| `themeProvider` | `Notifier<AppPalette>` | Palette de couleurs active (5 thèmes) + persistance |
| `genFilterProvider` | `Notifier<Set<int>>` | Générations sélectionnées pour le jeu + persistance |
| `caughtCountProvider` | `Provider<int>` | Nombre de Pokémon capturés (dérivé de pokedexProvider) |

#### Pages

| Fichier | Rôle |
| --- | --- |
| `main_page.dart` | Hub de navigation par onglets (Jeu / Pokédex / Système) |
| `guess_page.dart` | Écran principal du jeu (silhouette, input, lives, score) |
| `game_over_page.dart` | Écran de fin de partie avec stats de session |
| `pokemon_list.dart` | Pokédex : liste filtrée + recherche par nom |
| `pokemon_detail.dart` | Fiche détaillée : stats, type, genus, toggle normal/shiny |
| `system_page.dart` | Paramètres (langue, palette) et statistiques globales |

#### Widgets notables

- **Réutilisables** : `PokemonImage`, `PokemonTile`, `PokemonTypeWidget`, `ScanlineOverlay`.
- **guess/** : `GuessSilhouette`, `GuessInputSection`, `LivesRow`, `ScoreBoard`, `GenFilterSection`.
- **detail/** : `PokemonDetailTop`, `PokemonStatsPanel`.
- **game_over/** : `GameOverHeader`, `GameOverStats`, `GameOverActions`, `HingeDivider`.
- **list/** : `PokedexListHeader`, `PokedexCountBar`.
- **system/** : `LanguagePicker`, `PalettePicker`, `SectionTitle`, `SystemHeader`, `SystemStats`.

#### Thème

`type_colors.dart` : couleur et libellé localisé par type Pokémon.

## Flux de données

```
UI (Consumer) → Notifier → GameEngine (règles) + Repository (données)
                                 → DataSource (SQLite / HTTP) → DTO → Entity
```

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.

## Mécaniques de jeu (résumé)

- **Vies** : 3 au départ ; une vie perdue par mauvaise réponse ; game over à 0.
- **Hints** : 3 au départ ; révèle partiellement le nom ; +1 tous les 5 bonnes réponses consécutives.
- **Skips** : 3 au départ ; passe au Pokémon suivant sans pénalité ; +1 tous les 10 bonnes réponses.
- **Score** : +10 pts normal, +20 pts shiny ; meilleur score persisté via SharedPreferences.
- **Shiny** : 1 chance sur 10 (`AppConstants.shinyOdds`).
- **Filtre de génération** : le joueur choisit parmi Gen I–IX ; persisté entre les sessions.
- **Acceptation bilingue** : le nom FR *ou* EN est accepté quelle que soit la langue de l'UI.

## Tests

- `test/domain/game_engine_test.dart` : règles du jeu.
- `test/data/pokemon_dto_test.dart` : parsing JSON ↔ DB.
- `test/data/pokemon_repository_test.dart` : logique du repository (datasources factices).
- `test/widget_test.dart` : smoke test de démarrage de l'app.