roadwave/docs/adr/020-librairies-flutter.md

ADR-020 : 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-010
• Background modes : geolocator + geofence_service approuvés stores
• Notifications : flutter_local_notifications conforme guidelines iOS/Android

Architecture

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-010 (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-010)
• ❌ 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-010

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

Packages Flutter : Voir ADR-018 - Librairies Flutter 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-010), é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-010 : Frontend Mobile (Flutter, architecture permissions)
• ADR-018 : Librairies Go (même format de documentation)
• flutter_bloc documentation
• just_audio repository
• geolocator documentation
• Apple CarPlay Developer Guide
• Android Auto Developer Guide