# ADR-022 : Librairies Flutter du Mobile

**Statut** : Accepté
**Date** : 2026-01-31

## Contexte

L'application mobile RoadWave (iOS/Android) nécessite des librairies tierces pour audio HLS, géolocalisation, notifications, state management, etc. Le choix doit privilégier :
- **Licences permissives** (MIT, Apache-2.0, BSD) sans restrictions commerciales
- **Maturité** et maintenance active (écosystème Flutter)
- **Performance native** (pas de bridge JS)
- **Support CarPlay/Android Auto**
- **Conformité stores** (App Store, Play Store)

## Décision

Utilisation de **8 librairies open-source** Flutter avec licences permissives.

### Core Stack

| Catégorie | Librairie | Licence | Justification |
|-----------|-----------|---------|---------------|
| **State Management** | `flutter_bloc` | MIT | Pattern BLoC, 11K+ stars, reactive streams |
| **Audio HLS** | `just_audio` | MIT | HLS natif, buffering adaptatif, background playback |
| **HTTP Client** | `dio` | MIT | Interceptors, retry logic, 12K+ stars |
| **Stockage sécurisé** | `flutter_secure_storage` | BSD-3 | Keychain iOS, KeyStore Android |
| **Cache images** | `cached_network_image` | MIT | LRU cache, placeholder support |

### Géolocalisation & Permissions

| Catégorie | Librairie | Licence | Justification |
|-----------|-----------|---------|---------------|
| **GPS temps réel** | `geolocator` | MIT | Mode voiture, high accuracy, background modes |
| **Geofencing** | `geofence_service` | MIT | Détection rayon 200m, mode piéton, économie batterie |
| **Notifications locales** | `flutter_local_notifications` | BSD-3 | Compteur dynamique, icônes custom, iOS/Android |

### Packages Additionnels (CarPlay/Android Auto)

| Catégorie | Librairie | Licence | Justification |
|-----------|-----------|---------|---------------|
| **CarPlay** | `flutter_carplay` | MIT | Intégration CarPlay native (communautaire) |
| **Android Auto** | `android_auto_flutter` | Apache-2.0 | Support Android Auto (communautaire) |
| **Permissions** | `permission_handler` | MIT | Gestion unifiée permissions iOS/Android |

## Alternatives considérées

### State Management
- **flutter_bloc** (choisi) : Pattern BLoC, testable, reactive
- **riverpod** : Plus moderne, moins mature
- **provider** : Simple mais limité pour app complexe
- **getx** : Performance mais opinions controversées

### Audio
- **just_audio** (choisi) : HLS natif, communauté active
- **audioplayers** : Moins mature pour streaming
- **flutter_sound** : Orienté recording, pas streaming

### Géolocalisation
- **geolocator** (choisi) : Standard Flutter, 1.2K+ stars
- **location** : Moins maintenu
- **background_location** : Spécifique background uniquement

## Justification

### Licences
- **7/8 librairies** : MIT (permissive totale)
- **1/8** : BSD-3 (permissive, compatible commercial)
- **Compatibilité totale** : Aucun conflit de licence, aucune restriction commerciale

### Maturité
- **flutter_bloc** : 11.6K stars, adoption large (state management standard)
- **just_audio** : 900+ stars, utilisé production (podcasts apps)
- **geolocator** : 1.2K stars, maintenu BaseFlow (entreprise Flutter)
- **dio** : 12K+ stars, client HTTP le plus utilisé Flutter

### Performance
- **Compilation native** : Dart → ARM64 (pas de bridge JS comme React Native)
- **just_audio** : Utilise AVPlayer (iOS) et ExoPlayer (Android) natifs
- **geolocator** : Accès direct CoreLocation (iOS) et FusedLocation (Android)
- **geofence_service** : Geofencing natif, minimise consommation batterie

### Conformité Stores
- **Permissions progressives** : `permission_handler` + stratégie ADR-014
- **Background modes** : `geolocator` + `geofence_service` approuvés stores
- **Notifications** : `flutter_local_notifications` conforme guidelines iOS/Android

## Architecture

```mermaid
graph TB
    subgraph UI["Presentation Layer"]
        Widgets["Flutter Widgets"]
        Bloc["flutter_bloc<br/>(State Management)"]
    end

    subgraph Data["Data Layer"]
        API["dio<br/>(HTTP Client)"]
        Storage["flutter_secure_storage<br/>(JWT Tokens)"]
        Cache["cached_network_image<br/>(Image Cache)"]
    end

    subgraph Services["Services Layer"]
        Audio["just_audio<br/>(HLS Streaming)"]
        GPS["geolocator<br/>(GPS Mode Voiture)"]
        Geofence["geofence_service<br/>(Mode Piéton)"]
        Notif["flutter_local_notifications<br/>(Alerts Locales)"]
        Perms["permission_handler<br/>(Permissions iOS/Android)"]
    end

    subgraph Platform["Platform Integration"]
        CarPlay["flutter_carplay<br/>(iOS)"]
        AndroidAuto["android_auto_flutter<br/>(Android)"]
    end

    Widgets --> Bloc
    Bloc --> API
    Bloc --> Audio
    Bloc --> GPS
    Bloc --> Geofence

    API --> Storage
    Widgets --> Cache

    GPS --> Perms
    Geofence --> Perms
    Geofence --> Notif

    Audio --> CarPlay
    Audio --> AndroidAuto

    classDef uiStyle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef dataStyle fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef serviceStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef platformStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

    class UI,Widgets,Bloc uiStyle
    class Data,API,Storage,Cache dataStyle
    class Services,Audio,GPS,Geofence,Notif,Perms serviceStyle
    class Platform,CarPlay,AndroidAuto platformStyle
```

## Conséquences

### Positives
- ✅ Aucune restriction licence commerciale (100% permissif)
- ✅ Stack cohérent avec ADR-014 (Frontend Mobile)
- ✅ Performance native (compilation ARM64 directe)
- ✅ Écosystème mature et documenté
- ✅ Support CarPlay/Android Auto via communauté
- ✅ Conformité stores (permissions progressives)

### Négatives
- ⚠️ **CarPlay/Android Auto** : Packages communautaires (pas officiels Flutter)
- ⚠️ **Géolocalisation background** : Scrutée par App Store (stratégie progressive requise, ADR-014)
- ❌ **Courbe d'apprentissage** : Dart + pattern BLoC à maîtriser
- ❌ **Tests stores** : Validation TestFlight (iOS) et Internal Testing (Android) obligatoires

### Dépendances pubspec.yaml

> **Note** : Les versions exactes seront définies lors de l'implémentation. Cette section indique les packages requis, non les versions à utiliser (qui évoluent rapidement dans l'écosystème Flutter).

**Core** :
- `flutter_bloc` - State management
- `just_audio` - Audio HLS streaming
- `dio` - HTTP client
- `flutter_secure_storage` - Stockage sécurisé JWT
- `cached_network_image` - Cache images

**Géolocalisation & Notifications** :
- `geolocator` - GPS haute précision
- `geofence_service` - Geofencing arrière-plan
- `flutter_local_notifications` - Notifications locales
- `permission_handler` - Gestion permissions

**CarPlay/Android Auto** (optionnels MVP) :
- `flutter_carplay` - Intégration CarPlay
- `android_auto_flutter` - Support Android Auto

### Migration depuis ADR-014

La section "Packages clés" de l'ADR-014 est désormais obsolète et doit référencer cet ADR :

> **Packages Flutter** : Voir [ADR-022 - Librairies Flutter](020-librairies-flutter.md) pour la liste complète, licences et justifications.

## Risques et Mitigations

### Risque 1 : CarPlay/Android Auto packages communautaires
- **Impact** : Maintenance non garantie par Flutter team
- **Mitigation** : Fork privé si besoin, contribution upstream, ou développement custom si critique

### Risque 2 : Validation App Store (permissions background)
- **Impact** : Taux de rejet ~70% si mal justifié
- **Mitigation** : Stratégie progressive (ADR-014), écrans d'éducation, tests beta TestFlight

### Risque 3 : Performance audio HLS en arrière-plan
- **Impact** : Interruptions si OS tue l'app
- **Mitigation** : Background audio task iOS, foreground service Android (natif dans `just_audio`)

## Références

- ADR-014 : Frontend Mobile (Flutter, architecture permissions)
- ADR-020 : Librairies Go (même format de documentation)
- [flutter_bloc documentation](https://bloclibrary.dev/)
- [just_audio repository](https://pub.dev/packages/just_audio)
- [geolocator documentation](https://pub.dev/packages/geolocator)
- [Apple CarPlay Developer Guide](https://developer.apple.com/carplay/)
- [Android Auto Developer Guide](https://developer.android.com/training/cars)