# Architecture du Projet - Pokéguess

## Vue d'ensemble

Application Flutter affichant les 151 premiers Pokémon avec noms en français, via l'API Tyradex et cache local SQLite.

### Informations

- **Version** : 1.0.0+1
- **SDK** : Flutter >=3.1.0 <4.0.0
- **Plateformes** : Android, iOS, Web, macOS, Linux, Windows

## Architecture Générale

L'application suit une architecture en couches (layered architecture) avec une séparation claire des responsabilités :

```txt
┌─────────────────────────────────────────┐
│         Couche Présentation             │
│     (Pages & Components/Widgets)        │
├─────────────────────────────────────────┤
│         Couche Métier                   │
│           (Models)                      │
├─────────────────────────────────────────┤
│         Couche Services                 │
│      (API & Database & Utils)           │
└─────────────────────────────────────────┘
```

## Structure du Projet

```md
lib/
├── main.dart                    # Point d'entrée de l'application
├── api/
│   └── pokemon_api.dart         # Service d'accès à l'API Tyradex
├── components/
│   ├── pokemon_tile.dart        # Widget de tuile pour afficher un Pokémon
│   └── pokemon_type.dart        # Widget pour afficher le type d'un Pokémon
├── database/
│   └── pokedex_database.dart    # Gestion de la base de données SQLite
├── models/
│   └── pokemon.dart             # Modèle de données Pokémon
├── pages/
│   ├── pokemon_detail.dart      # Page de détail d'un Pokémon
│   └── pokemon_list.dart        # Page de liste des Pokémon
└── utils/
    └── pokemon_type.dart        # Utilitaires pour les types de Pokémon
```

## Composants Principaux

### 1. Point d'Entrée

[main.dart](../lib/main.dart) - Initialisation de l'application

- Thème Material Design 3
- Routes : `/` (liste) et `/pokemon-detail` (détail)

### 2. Couche Présentation

#### Pages

##### PokemonListPage ([pokemon_list.dart](../lib/pages/pokemon_list.dart))

StatefulWidget affichant une grille de 151 Pokémon (2 colonnes mobile, 4 web) via `GridView.builder` et `FutureBuilder`.

##### PokemonDetailPage ([pokemon_detail.dart](../lib/pages/pokemon_detail.dart))

StatefulWidget affichant les détails d'un Pokémon avec toggle shiny (`_isShiny`) via `GestureDetector`.

#### Components

##### PokemonTile ([pokemon_tile.dart](../lib/components/pokemon_tile.dart))

StatefulWidget affichant une carte Pokémon (image + nom) avec navigation vers détail au tap.

##### PokemonTypeWidget ([pokemon_type.dart](../lib/components/pokemon_type.dart))

StatelessWidget affichant un badge coloré par type.

### 3. Couche Modèle

#### Pokemon ([pokemon.dart](../lib/models/pokemon.dart))

- **Propriétés** :
  - `name` : String - Nom du Pokémon
  - `id` : int - Numéro du Pokémon
  - `type1` : PokemonType - Type principal
  - `type2` : PokemonType? - Type secondaire (optionnel)

- **Propriétés calculées** : `imageUrl`, `shinyImageUrl`, `cryUrl`, `formatedName`, `type1Color`, `type2Color`, `type1Formated`, `type2Formated`
- **Méthodes** : `fromJson()`, `toJson()`, `fromID()` (cache + API)
- **Enum** : `PokemonType` (20 types)

### 4. Couche Services

#### PokemonApi ([pokemon_api.dart](../lib/api/pokemon_api.dart))

Communication avec Tyradex API (<https://tyradex.vercel.app>)

- `getPokemon(int id)` : Récupère un Pokémon depuis l'API avec nom en français
- Exception levée si code HTTP ≠ 200

#### PokedexDatabase ([pokedex_database.dart](../lib/database/pokedex_database.dart))

Gestion SQLite locale (CRUD complet)

- **Schéma** : `pokemon (id, name, type1, type2)`
- **Méthodes** : `initDatabase()`, `getDatabase()`, `insertPokemon()`, `getPokemonList()`, `getPokemon()`, `deletePokemon()`, `deleteAllPokemon()`, `updatePokemon()`
- Non disponible sur Web (`kIsWeb`)

#### Utils ([pokemon_type.dart](../lib/utils/pokemon_type.dart))

- `frenchTypeToEnum()` : Conversion types français (API) vers enum
- `typeToColor()` : Mapping type → couleur
- `formatedTypeName()` : Formatage nom de type

## Flux de Données

### Récupération d'un Pokémon

```md
1. PokemonListPage demande Pokemon.fromID(id)
                ↓
2. Vérification dans PokedexDatabase (si non-web)
                ↓
3a. Si trouvé → Retour du Pokémon en cache
                ↓
3b. Si non trouvé → Appel à PokemonApi.getPokemon(id)
                ↓
4. Parsing JSON et création de l'objet Pokemon
                ↓
5. Sauvegarde dans PokedexDatabase (si non-web)
                ↓
6. Retour du Pokemon à la vue
```

### Navigation

```md
PokemonListPage
      ↓ (tap sur PokemonTile)
Navigator.pushNamed('/pokemon-detail', arguments: pokemon)
      ↓
PokemonDetailPage (récupère le pokemon via ModalRoute)
```

## Patterns et Bonnes Pratiques

**Patterns** : Repository (classe `Pokemon`), Factory (`fromJson()`), FutureBuilder (async)

**Plateformes** : Détection Web via `kIsWeb`, adaptation colonnes grille

**Erreurs** : Try/catch + logs, vérification HTTP, messages dans FutureBuilder

## Dépendances

**Production** : `flutter`, `cupertino_icons` (^1.0.2), `sqflite` (^2.3.0), `http` (^1.1.0)

**Développement** : `flutter_test`, `flutter_lints` (^2.0.0)

## Points d'Extension

1. Recherche et filtres (type, génération)
2. Mode jeu (deviner à partir de silhouette, score)
3. Système de favoris
4. Lecture audio des cris
5. Détails enrichis (stats, évolutions, capacités)
6. Préchargement offline des 151 Pokémon
7. Tests unitaires et d'intégration

## Limitations

1. Pas de persistance locale sur Web
2. Limité à 151 Pokémon (Gen 1)
3. Gestion d'erreur minimale
4. Pas d'internationalisation
5. Pas de tests automatisés

## Notes Techniques

- Material Design 3
- Images : repository Yarkis01/TyraDex (GitHub)
- API : Tyradex API (https://tyradex.vercel.app)
- Noms de Pokémon en français
- Routage : routes nommées Flutter
- Pas de state management externe

---

**Dernière mise à jour** : 2 février 2026