Zum Inhalt

Frontend-Architektur

Das KanjiIQ-Frontend ist eine Flutter Web Anwendung, die von Nginx bereitgestellt wird. Es unterstützt Offline-Lernen, automatische Locale-Erkennung und 51 UI-Sprachen.

Build-Pipeline

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]

Das Frontend wird als mehrstufiges Docker-Image erstellt:

  1. Build-Stufe (Ubuntu 22.04): Installiert Flutter SDK, generiert Lokalisierungen, erstellt Release-Web-Assets
  2. Produktionsstufe (Nginx Alpine): Stellt statische Dateien mit Gzip, Caching und SPA-Routing bereit

Schlüsseltechnologien

Technologie Version Zweck
Flutter Latest stable UI-Framework
Provider ^6.1.1 Zustandsverwaltung
GoRouter ^13.0.0 Deklaratives Routing
sqflite ^2.3.2 Lokales SQLite für Offline-Cache
connectivity_plus ^5.0.2 Netzwerkzustandserkennung
SharedPreferences ^2.2.2 Persistenter Schlüssel-Wert-Speicher
flutter_animate ^4.5.0 UI-Animationen

Anwendungsstruktur

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)

Offline-First-Architektur

KanjiIQ funktioniert ohne Internetverbindung dank einer Cache-First-Datenstrategie:

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 speichert Kanji und Vokabeln lokal für den Offline-Zugriff
  • ConnectivityService überwacht Netzwerkzustandsänderungen
  • SyncService führt Hintergrundsynchronisation durch, wenn die Verbindung wiederhergestellt wird
  • SharedPreferences speichert die Locale-Konfiguration für 7 Tage im Cache

Nginx-Konfiguration

Der Nginx-Server (nginx.frontend.conf) übernimmt:

  • SPA-Routing: Alle Routen fallen auf index.html zurück für Flutters clientseitiges Routing
  • API-Proxying: /api/-Anfragen werden an localhost:8080 (den Backend-Container im selben Pod) weitergeleitet
  • Gzip-Komprimierung: Aktiviert für Text, CSS, JS, JSON und SVG
  • Cache-Steuerung: 1 Jahr Cache für versionierte statische Assets, kein Cache für index.html
  • Sicherheitsheader: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
  • Gesundheitsprüfung: /health-Endpunkt für Kubernetes-Probes