ADR-008: Architecture de l'application mobile ObeeSmart

Date: 2026-02-09
Statut: Accepté
Décideurs: Équipe ObeeSmart
Contexte technique: ObeeSmart Mobile v1.0.0


Contexte

ObeeSmart est une plateforme web de monitoring apicole (Node.js/Express) qui nécessitait un compagnon mobile pour permettre aux apiculteurs de :

  • Consulter l'état de leurs ruches sur le terrain (souvent sans accès PC)
  • Recevoir des alertes push en temps réel (poids, température, frelons)
  • Photographier des cadres pour analyse IA directement depuis le rucher
  • Saisir visites, traitements et récoltes en mobilité

Le choix d'architecture devait répondre à plusieurs contraintes :

  • Équipe réduite (1 développeur full-stack)
  • Réutilisation maximale du backend existant
  • Déploiement sans dépendre du Play Store (APK auto-hébergé)
  • Support Android obligatoire, iOS souhaitable à terme

Décisions

1. Framework : React Native via Expo SDK 54

Choix : Expo (managed workflow → prebuild) avec React Native 0.81.5 et New Architecture activée.

Alternatives considérées :

Option Avantages Inconvénients
Expo (choisi) DX excellente, OTA updates, prebuild pour modules natifs Taille APK (~104 MB), certaines limites natives
Flutter Performances UI, un seul langage Pas de réutilisation JS, écosystème packages différent
PWA Zéro install, même codebase web Pas de push fiable sur Android, pas d'accès caméra natif, UX inférieure
Natif Kotlin Performance optimale Temps de dev x3, pas de partage de code iOS

Justification : Expo permet de partager l'expertise JavaScript/TypeScript du backend, fournit un système de push notifications intégré (Expo Push Service), et supporte le build local d'APK sans compte Play Store. Le passage en mode prebuild permet d'accéder aux modules natifs (Firebase, caméra) tout en gardant la DX Expo.

2. Authentification : JWT dual-token via API dédiée

Architecture :

┌─────────────────┐     POST /api/mobile/auth/login      ┌──────────────┐
│   App Mobile    │ ──────────────────────────────────────▶│   Backend    │
│                 │ ◀──────────────────────────────────────│  Express.js  │
│  SecureStore    │  { accessToken (JWT 1h),               │              │
│  ├─ access_tk   │    refreshToken (hex 30j) }            │  tokens DB   │
│  ├─ refresh_tk  │                                        │  (type:      │
│  └─ user_json   │  GET /api/mobile/* (Bearer JWT)        │  mobile_     │
│                 │ ──────────────────────────────────────▶│  refresh)    │
└─────────────────┘                                        └──────────────┘
  • Access token : JWT pur (1h), non stocké en DB, vérifié par signature
  • Refresh token : Hex aléatoire (30j), stocké dans la table tokens (type mobile_refresh)
  • Middleware verifyMobileToken : Vérifie le JWT, puis injectSession simule une session Express pour réutiliser les routes existantes
  • Proxy transparent : /api/mobile/proxy/* redirige vers les routes web existantes avec JWT auth

Justification : Le backend web utilise des sessions Express (cookie-based). Plutôt que de refondre toute l'auth, le middleware injectSession crée un objet req.session synthétique à partir du JWT, permettant de réutiliser 100% des routes existantes via le proxy.

3. Communication API : Axios + intercepteurs automatiques

Client HTTP (src/api/client.ts) :

Requête → [Interceptor: ajoute Bearer token] → Backend
                                                    │
Réponse 200 ← ──────────────────────────────────────┘
Réponse 401 → [Interceptor: refresh token] → retry requête originale
                    │
                    └─ refresh échoue → clearAll() → écran login
  • Base URL : Configurée dans app.json (extra.apiUrl), fallback 10.0.2.2:3000 pour émulateur
  • Timeout : 15 secondes
  • Queue de refresh : Les requêtes concurrentes en 401 attendent un seul refresh, puis sont rejouées
  • 15 modules API : auth, dashboard, devices, alerts, beekeeper, analytics, ai, photos, profile

4. État applicatif : React Query + AuthContext

Choix : Pas de Redux/Zustand. Deux mécanismes complémentaires :

Couche Outil Responsabilité
Données serveur @tanstack/react-query v5 Cache, refetch, stale-while-revalidate, retry
Auth globale React Context (AuthContext) user, isAuthenticated, login/logout/refresh
Stockage local expo-secure-store Tokens JWT, données user persistées

Configuration React Query :

  • staleTime : 5 min (dashboard), 10 min (profil/subscription)
  • gcTime : 30 min
  • retry : 2 tentatives
  • refetchInterval : 60s sur le dashboard (polling léger)

Justification : L'app est principalement en lecture (consultation de données capteurs). React Query gère naturellement le cache, la déduplication et le refresh en arrière-plan. Un store global (Redux) ajouterait de la complexité sans bénéfice pour ce cas d'usage.

5. Navigation : React Navigation 7 avec typed params

Structure :

RootNavigator
├── AuthStack (non authentifié)
│   ├── Login
│   ├── Register
│   └── ForgotPassword
│
└── MainTabs (authentifié) — 6 onglets
    ├── Dashboard (écran unique)
    ├── DevicesStack
    │   ├── DevicesList
    │   ├── ScaleDetail
    │   ├── CentraleDetail
    │   ├── ScreenDetail
    │   └── DisplayDetail
    ├── Analytics (écran unique)
    ├── AlertsStack
    │   ├── AlertsList
    │   └── AlertDetail
    ├── BeekeeperStack (16 écrans)
    │   ├── BeekeeperHome
    │   ├── Ruchiers → RuchierDetail → RucheDetail
    │   ├── Visits → VisitForm / VisitDetail
    │   ├── Treatments → TreatmentForm
    │   ├── Harvests → HarvestForm
    │   ├── Reports
    │   └── AI (Camera → AnalysisResult, AnalysisList)
    └── ProfileStack
        ├── Profile → EditProfile
        ├── Subscription
        ├── NotificationPrefs
        ├── Achievements
        ├── Leaderboard
        └── About
  • 33 écrans au total (3 auth + 30 app)
  • Typed navigation : Chaque stack a un ParamList TypeScript pour la sécurité de typage des params de navigation
  • Tab reset : Re-tap sur un onglet actif remonte au premier écran du stack

6. Notifications push : Expo Push Service + Firebase FCM

Architecture :

┌──────────┐    Expo Push Token    ┌───────────┐    HTTP POST     ┌───────────┐
│ App      │ ─────────────────────▶│  Backend  │ ──────────────▶  │ Expo Push │
│ Mobile   │                       │           │                  │  Service  │
│          │◀─── Push via FCM ─────│           │◀── Ticket/Receipt│           │
└──────────┘                       └───────────┘                  └─────┬─────┘
                                                                       │
                                                                  ┌────▼─────┐
                                                                  │ Firebase  │
                                                                  │   FCM     │
                                                                  └──────────┘

Flux :

  1. App authentifiée → registerForPushNotifications() dans AuthContext
  2. Expo génère un push token via FCM (nécessite google-services.json)
  3. Token envoyé au backend → stocké dans User.onboarding_data.push_tokens[] (JSONB)
  4. Alerte déclenchée → NotificationService → PushService.sendPushNotification(userId)
  5. Backend utilise expo-server-sdk pour envoyer via Expo Push Service → FCM → appareil

Configuration requise :

  • google-services.json dans mobile/ (copié par expo prebuild)
  • Service Account FCM V1 uploadé via eas credentials
  • EAS Project ID dans app.json → extra.eas.projectId
  • Canal Android "alerts" (importance HIGH, vibration, couleur amber)

7. Thème : Dark-first avec accents amber

Palette :

Token Valeur Usage
background #0f0f1a Fond principal
surface #1a1a2e Surfaces élevées
card #1e1e28 Cartes et conteneurs
honey #f59e0b Accent principal, CTA, icônes actifs
honeyLight rgba(245,158,11,0.15) Badges, fonds subtils
text #e2e8f0 Texte principal
textSecondary #94a3b8 Texte secondaire
success/warning/danger/info Vert/Amber/Rouge/Bleu Statuts et alertes

Typographie : Système natif, 12 styles prédéfinis de h1 (28px bold) à badge (10px bold).

8. Build et distribution : APK auto-hébergé

Choix : Build local via Gradle, distribution via le site web public.

expo prebuild --platform android    →  Génère android/ avec plugins
cd android && ./gradlew assembleRelease  →  APK signé (debug keystore)
cp app-release.apk public/downloads/obeesmart.apk
push-toharbor.sh                    →  Déploie le backend avec l'APK
  • Pas de Play Store : L'app est distribuée via https://obeesmart.bijon.fr/downloads/obeesmart.apk
  • Section téléchargement sur la page d'accueil publique avec feature tags
  • Signing : Debug keystore pour l'instant (suffisant pour distribution directe)

Justification : Le Play Store impose des délais de review, un compte développeur payant, et des contraintes de metadata. Pour un usage interne/communautaire, l'APK direct est plus simple et instantané.

9. Backend mobile : Route unique /api/mobile/*

Fichier : routes/api-mobile.js (~2200 lignes)

Structure :

/api/mobile/
├── auth/           (login, register, refresh, logout)
├── dashboard       (stats agrégées : devices, weather, KPIs, trends, upcoming)
├── devices/        (scales, screens, centrales, displays + history)
├── alerts/         (list, detail, acknowledge)
├── beekeeper/      (ruchiers, ruches, visits, treatments, harvests, reports)
├── analytics/      (weight-chart, production, alert-stats, hornets)
├── ai/             (analyze, history, credits)
├── profile/        (me, update, subscription, achievements)
├── push/           (register, unregister)
├── photos/         (upload, list)
└── proxy/*         (passthrough vers routes web existantes)

Middlewares :

  • verifyMobileToken : Vérifie le JWT et charge l'utilisateur
  • injectSession : Crée req.session = { user, userId } pour compatibilité routes web
  • Pas de session Express côté mobile → stateless

Inventaire technique

Fichiers source

Catégorie Fichiers Lignes (approx.)
Écrans 27 .tsx ~6000
API modules 10 .ts ~800
Navigation 7 .tsx ~500
Composants 6 .tsx ~600
Contextes 1 .tsx ~130
Services 2 .ts ~100
Thème 2 .ts ~80
Types 1 .ts ~300
Backend API 1 .js ~2200
Total 57 front + 1 back ~10700

Dépendances clés

Package Version Rôle
expo 54.0.33 Runtime & tooling
react-native 0.81.5 Framework UI natif
react 19.1.0 Bibliothèque UI
typescript 5.9.2 Typage statique (strict)
@tanstack/react-query 5.90.20 Cache & data fetching
axios 1.13.4 Client HTTP
@react-navigation/* 7.x Navigation
expo-notifications 0.32.16 Push notifications
expo-camera 17.0.10 Capture photo IA
expo-secure-store 15.0.8 Stockage sécurisé tokens
react-native-chart-kit 6.12.0 Graphiques analytics
expo-server-sdk 5.x Backend : envoi push

Conséquences

Positif

  • Temps de développement réduit : Partage de l'écosystème JS/TS avec le backend
  • Backend inchangé : Le middleware injectSession + proxy évite de toucher aux routes web existantes
  • Push instantané : Expo Push Service abstrait la complexité FCM/APNs
  • Distribution agile : Pas de review Play Store, mise à jour immédiate
  • Type safety : TypeScript strict sur tout le code mobile, params de navigation typés

Négatif

  • Taille APK : ~104 MB (Hermes + tous les assets Expo)
  • Dépendance Expo : Expo Push Service est un SPOF pour les notifications
  • Pas d'OTA : Sans EAS Update, chaque changement nécessite un rebuild APK complet
  • Debug keystore : Pas de signing de production → avertissement Android à l'installation
  • iOS non couvert : L'architecture le permet mais aucun build iOS n'est configuré

Risques et mitigations

Risque Probabilité Impact Mitigation
Expo Push Service indisponible Faible Moyen Fallback Telegram existant
Token refresh race condition Faible Faible Queue de refresh implémentée
APK non signé rejeté par Android Moyen Moyen Prévoir signing keystore de production
Mise à jour manuelle des APK Moyen Faible Prévoir EAS Update ou versioning avec notification in-app

Évolutions possibles

  1. EAS Build + OTA Updates : Permettre les mises à jour over-the-air sans redistribuer l'APK
  2. Signing de production : Générer un keystore dédié pour supprimer l'avertissement Android
  3. Build iOS : Ajouter la configuration iOS dans app.json et tester sur simulateur
  4. Mode hors-ligne : Utiliser React Query persistQueryClient pour cacher les données localement
  5. Deep linking : Activer le scheme obeesmart:// pour ouvrir des écrans depuis les notifications push
  6. Publication Play Store : Quand le nombre d'utilisateurs le justifiera

Références