Saltar a contenido

Arquitectura del frontend

El frontend de KanjiIQ es una aplicación Flutter Web servida por Nginx. Soporta estudio offline, detección automática de locale y 51 idiomas de UI.

Pipeline de compilación

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]

El frontend se construye como una imagen Docker multi-etapa:

  1. Etapa de compilación (Ubuntu 22.04): Instala Flutter SDK, genera localizaciones, compila los assets web de producción
  2. Etapa de producción (Nginx Alpine): Sirve archivos estáticos con gzip, caché y enrutamiento SPA

Tecnologías clave

Tecnología Versión Propósito
Flutter Latest stable Framework de UI
Provider ^6.1.1 Gestión de estado
GoRouter ^13.0.0 Enrutamiento declarativo
sqflite ^2.3.2 SQLite local para caché offline
connectivity_plus ^5.0.2 Detección de estado de red
SharedPreferences ^2.2.2 Almacenamiento persistente clave-valor
flutter_animate ^4.5.0 Animaciones de UI

Estructura de la aplicación

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)

Arquitectura offline-first

KanjiIQ funciona sin conexión a internet usando una estrategia de datos 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 almacena kanji y vocabulario localmente para acceso offline
  • ConnectivityService monitorea los cambios de estado de la red
  • SyncService ejecuta sincronización en segundo plano cuando se recupera la conectividad
  • SharedPreferences almacena en caché la configuración de locale durante 7 días

Configuración de Nginx

El servidor Nginx (nginx.frontend.conf) gestiona:

  • Enrutamiento SPA: Todas las rutas redirigen a index.html para el enrutamiento del lado del cliente de Flutter
  • Proxy de API: Las solicitudes /api/ se redirigen a localhost:8080 (el contenedor backend en el mismo pod)
  • Compresión gzip: Habilitada para texto, CSS, JS, JSON y SVG
  • Control de caché: Caché de 1 año para assets estáticos versionados, sin caché para index.html
  • Cabeceras de seguridad: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
  • Health check: Endpoint /health para las sondas de Kubernetes