Architecture du frontend¶

Le frontend de KanjiIQ est une application Flutter Web servie par Nginx. Il prend en charge l'étude hors ligne, la détection automatique de la locale et 51 langues d'interface.

Pipeline de build¶

graph LR
    S[Flutter Source] --> GL[flutter gen-l10n<br/>Generate 51 ARB files]
    GL --> B[flutter build web<br/>--release]
    B --> N[Nginx Alpine<br/>Static Serve]

Le frontend est construit sous forme d'image Docker multi-étapes :

Étape de build (Ubuntu 22.04) : Installe le SDK Flutter, génère les localisations, compile les assets web en mode release
Étape de production (Nginx Alpine) : Sert les fichiers statiques avec gzip, mise en cache et routage SPA

Technologies clés¶

Technologie	Version	Fonction
Flutter	Latest stable	Framework d'interface
Provider	^6.1.1	Gestion d'état
GoRouter	^13.0.0	Routage déclaratif
sqflite	^2.3.2	SQLite local pour cache hors ligne
connectivity_plus	^5.0.2	Détection de l'état réseau
SharedPreferences	^2.2.2	Stockage persistant clé-valeur
flutter_animate	^4.5.0	Animations de l'interface

Structure de l'application¶

frontend/lib/
├── main.dart                    # App entry point, Provider setup
├── models/                      # Data models (Kanji, Vocabulary)
├── providers/                   # State management
│   └── study_provider.dart      # Flashcard session state
├── repositories/                # Data access layer
│   ├── kanji_repository.dart    # Cache-first kanji fetching
│   └── vocabulary_repository.dart
├── screens/                     # UI screens
│   ├── home_screen.dart         # Language & level selection
│   ├── study_screen.dart        # Flashcard presentation
│   └── results_screen.dart      # Session summary
├── services/                    # Business logic
│   ├── api_service.dart         # REST API client
│   ├── database_helper.dart     # Local SQLite operations
│   ├── locale_detector.dart     # Device locale detection
│   ├── locale_preferences.dart  # Language preference management
│   ├── connectivity_service.dart # Online/offline detection
│   └── sync_service.dart        # Background data synchronization
└── l10n/                        # Localization
    ├── app_en.arb               # English (template)
    ├── app_ja.arb               # Japanese
    └── ... (51 ARB files)

Architecture hors ligne d'abord¶

KanjiIQ fonctionne sans connexion Internet grâce à une stratégie de données cache-first :

graph TD
    A[User requests data] --> B{Local cache<br/>available?}
    B -->|Yes| C[Return cached data]
    B -->|No| D{Online?}
    D -->|Yes| E[Fetch from API]
    D -->|No| F[Show offline message]
    E --> G[Store in SQLite]
    G --> C
    C --> H[Background sync<br/>when online]

SQLite stocke les kanji et le vocabulaire localement pour l'accès hors ligne
ConnectivityService surveille les changements d'état du réseau
SyncService exécute la synchronisation en arrière-plan lorsque la connectivité revient
SharedPreferences met en cache la configuration de la locale pendant 7 jours

Configuration Nginx¶

Le serveur Nginx (nginx.frontend.conf) gère :

Routage SPA : Toutes les routes redirigent vers index.html pour le routage côté client de Flutter
Proxy API : Les requêtes /api/ sont redirigées vers localhost:8080 (le conteneur backend dans le même pod)
Compression Gzip : Activée pour le texte, CSS, JS, JSON et SVG
Contrôle du cache : Cache d'un an pour les assets statiques versionnés, pas de cache pour index.html
En-têtes de sécurité : X-Frame-Options, X-Content-Type-Options, Referrer-Policy
Vérification de santé : Endpoint /health pour les sondes Kubernetes