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(typemobile_refresh) - Middleware
verifyMobileToken: Vérifie le JWT, puisinjectSessionsimule 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), fallback10.0.2.2:3000pour é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 minretry: 2 tentativesrefetchInterval: 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
ParamListTypeScript 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 :
- App authentifiée →
registerForPushNotifications()dans AuthContext - Expo génère un push token via FCM (nécessite
google-services.json) - Token envoyé au backend → stocké dans
User.onboarding_data.push_tokens[](JSONB) - Alerte déclenchée →
NotificationService→PushService.sendPushNotification(userId) - Backend utilise
expo-server-sdkpour envoyer via Expo Push Service → FCM → appareil
Configuration requise :
google-services.jsondansmobile/(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'utilisateurinjectSession: Créereq.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
- EAS Build + OTA Updates : Permettre les mises à jour over-the-air sans redistribuer l'APK
- Signing de production : Générer un keystore dédié pour supprimer l'avertissement Android
- Build iOS : Ajouter la configuration iOS dans
app.jsonet tester sur simulateur - Mode hors-ligne : Utiliser React Query
persistQueryClientpour cacher les données localement - Deep linking : Activer le scheme
obeesmart://pour ouvrir des écrans depuis les notifications push - Publication Play Store : Quand le nombre d'utilisateurs le justifiera
Références
- Expo SDK 54 Documentation
- React Navigation 7
- TanStack React Query v5
- Expo Push Notifications Guide
- ADR-007: Intégration S3 pour rapports et photos