Architecture & Ingénierie
Hola Africa

Hola Africa est une interface commerciale et technique placée entre un partenaire opérateur satellite (non encore identifié à ce stade — Starlink, AST SpaceMobile, ou MVNE satellite white-label) et des millions d'utilisateurs en Afrique centrale et de l'Ouest. Notre rôle est d'orchestrer la vente, le provisionnement et le support de cette connectivité via une application mobile fluide, en s'appuyant sur les paiements Mobile Money locaux.

Les 3 promesses produit

1. 01
   Connectivité sans opérateur local
   L'utilisateur n'a besoin ni de SIM physique, ni de carte de recharge. La connexion arrive par satellite sur son terminal compatible.
2. 02
   Paiement 100% Mobile Money
   Orange Money, MTN MoMo, Wave, Moov Money — aucune carte bancaire requise. Paiement micro-forfait en quelques secondes.
3. 03
   Activation instantanée
   Du paiement au premier octet : moins de 30 secondes. Le système backend déclenche le provisionnement dès confirmation webhook du paiement.

Backend & Infrastructure

Frontend Web & Back-Office

Mobile

DevOps & Infrastructure Cloud

Design & Outils transverses

L'architecture est orientée microservices, découpée selon les domaines métier. Chaque service est indépendant, déployable séparément, et communique via l'API Gateway (pour les requêtes synchrones) ou RabbitMQ (pour les événements asynchrones).

Le flux critique : de l'achat à la connectivité

1. 01
   L'utilisateur sélectionne un forfait dans l'app Flutter
   Il choisit la durée (1h, 24h, 7 jours) et confirme. L'app appelle le Payment Service via l'API Gateway.
2. 02
   Le Payment Service initie la collecte Mobile Money
   Il appelle CinetPay ou l'API MoMo directe. L'utilisateur reçoit une notification USSD/push pour confirmer le paiement. La transaction est enregistrée en base avec le statut PENDING.
3. 03
   Webhook de confirmation asynchrone
   CinetPay envoie un webhook signé (HMAC) vers le backend. Le Payment Service valide la signature, passe la transaction en PAID, et publie l'événement payment.confirmed dans RabbitMQ.
4. 04
   Le Provisioning Service consomme l'événement
   Il appelle l'API du partenaire satellite pour activer la connectivité sur le terminal de l'utilisateur (identifié par son device ID ou numéro de compte Hola Africa).
5. 05
   Confirmation et notification
   Le Notification Service envoie un push Firebase confirmant l'activation. L'app Flutter reçoit la mise à jour via WebSocket et affiche l'écran de connectivité active.
6. 06
   Si le provisionnement échoue
   Le Provisioning Service retente automatiquement (backoff exponentiel, max 3 fois). Si toujours en échec, il publie prov.failed → remboursement automatique via API de décaissement Mobile Money.

Typologies de partenaires satellites à évaluer

Ce que le Provisioning Service doit être capable de faire

Indépendamment du partenaire retenu, le Provisioning Service backend doit supporter les opérations suivantes via l'API partenaire :

1. ACT
   Activer une session de connectivité
   En passant l'identifiant terminal unique de l'utilisateur, le forfait acheté et la date/heure de début.
2. MON
   Consulter la consommation en temps réel
   Pour afficher à l'utilisateur son solde de données restant dans l'app Flutter.
3. CUT
   Couper / suspendre une session
   En fin de forfait ou en cas de fraude détectée.
4. RPT
   Recevoir des webhooks de fin de session
   Le partenaire notifie quand le forfait est épuisé, pour déclencher une notif push à l'utilisateur et proposer le renouvellement.
5. LOG
   Logger toutes les interactions
   Pour la réconciliation, le support client et les audits réglementaires.

Disponibilité attendue et gestion de la résilience

La connectivité satellite D2C en Afrique subsaharienne offre une disponibilité de 60% à 75% selon les zones géographiques, la météo, et l'orbite utilisée (LEO > GEO en disponibilité, mais plus complexe). Le système doit être conçu pour absorber cette réalité :

Responsabilités du backend

Le backend est architecturé en microservices NestJS indépendants. Chaque service a sa propre responsabilité, sa propre base de données logique (schéma PostgreSQL séparé), et communique via l'API Gateway (sync) ou RabbitMQ (async).

Les 5 microservices à développer

Architecture des données (schéma conceptuel)

Patterns critiques à implémenter

Les deux applications web à développer

Fonctionnalités du Back-Office (détail)

1. TXN
   Dashboard Transactions
   Liste paginée de toutes les transactions avec filtres (statut, pays, opérateur de paiement, date). Vue détail avec timeline complète : paiement → provisionnement → résultat.
2. KYC
   File d'attente KYC
   Affichage des documents CNI soumis en attente de validation manuelle. Interface d'approbation/rejet avec motif. Intégration future avec Smile Identity pour l'automatisation biométrique.
3. RFD
   Module Remboursements
   Remboursements manuels sur les transactions FAILED orphelines. Appel direct à l'API de décaissement CinetPay depuis l'interface. Log automatique avec justificatif.
4. KPI
   Dashboard Finance & KPIs
   GMV journalier/mensuel, marge brute par pays, taux d'échec de provisionnement, taux de conversion, nouveaux utilisateurs actifs. Graphiques recharts.
5. USR
   Gestion Utilisateurs
   Recherche par numéro de téléphone ou device ID. Historique complet de l'utilisateur. Actions : suspendre compte, réinitialiser KYC, forcer déconnexion.

Structure des routes Next.js (App Router)

Architecture Flutter recommandée

Architecture Feature-First avec Clean Architecture par feature. Chaque feature (auth, plans, purchase, connectivity-status) est un module indépendant avec ses propres couches : data, domain, presentation.

Gestion de l'état avec Riverpod

1. AUTH
   AuthNotifier
   État global de l'authentification. Persiste les tokens JWT (Flutter Secure Storage). Gère le refresh silencieux en arrière-plan quand l'access token expire.
2. CONN
   ConnectivityStatusNotifier
   Mise à jour temps réel de l'état de la connectivité de l'utilisateur. Écoute le WebSocket du backend et notifie l'UI instantanément lors d'un changement de statut.
3. PAY
   PurchaseNotifier
   Orchestre le flux d'achat : sélection forfait → initiation paiement → polling statut → confirmation. Gère les états loading, success, error avec des messages utilisateur contextuels.

Points d'attention critiques pour le dev mobile

Architecture d'infrastructure par environnement

Pipeline CI/CD GitHub Actions

Stratégie de déploiement Kubernetes

1. HPA
   Horizontal Pod Autoscaler sur le Payment Service
   Le Payment Service est le plus sollicité lors des pics. L'HPA doit scaler automatiquement de 2 à 10 replicas selon la charge CPU/mémoire. Le Provisioning Service doit également être scalé indépendamment.
2. RD
   Rolling Deployment sans interruption
   Chaque déploiement utilise une stratégie Rolling Update : les nouveaux pods démarrent avant que les anciens ne soient arrêtés. Zero-downtime garanti même lors des mises à jour en heures de pointe.
3. NS
   Namespaces par environnement
   hola-prod, hola-staging, hola-monitoring. Les secrets Kubernetes (API keys, DB passwords) sont gérés via AWS Secrets Manager avec External Secrets Operator.
4. BK
   Backups PostgreSQL automatiques
   Snapshots RDS quotidiens avec rétention 30 jours. WAL archiving en continu pour le point-in-time recovery. En cas d'incident, retour en arrière possible à la minute près.

Stack de monitoring

Rôle du designer dans l'équipe Hola Africa

Le designer est la source de vérité visuelle de toute la plateforme. Son travail en Figma précède chaque développement. Aucune interface ne doit être codée sans maquette validée. Il est le garant de la cohérence entre l'app Flutter, le back-office et le site marketing.

Livrables attendus par phase

Directives brand Hola Africa

Handoff designer → développeur

1. TKN
   Export des Design Tokens
   Exporter les variables Figma en JSON. Le DevFlutter les convertit en ThemeData Flutter. Le DevFrontend les importe dans tailwind.config.js. Un seul fichier source = cohérence garantie.
2. SPC
   Spécifications Figma complètes
   Chaque composant doit avoir des annotations : espacements exacts, tailles de texte, états (hover, focus, disabled, error). Utiliser le plugin Figma "Inspect" pour le handoff au développeur.
3. AST
   Assets exportés
   Icônes en SVG (pas en PNG). Illustrations en SVG ou WebP optimisé. Jamais de JPEG pour les assets UI. Nommage standardisé : ic_satellite_active.svg, ic_payment_success.svg.

Sécurité par couche

Niveau Réseau & Périmètre

Niveau Authentification

Niveau Paiement

Niveau Données & RGPD/ART

Niveau Secrets & Variables d'environnement

Audit de Sécurité

Le paiement est le premier événement de la chaîne de valeur. Sans paiement validé, pas de provisionnement. L'architecture de paiement doit être infaillible.

Stratégie d'intégration par pays

Le flux de paiement en détail

La réglementation camerounaise (décrets ART + directives BEAC) impose la vérification d'identité avant toute activation de service de connectivité. Le KYC n'est pas une option.

Processus KYC par étape

1. MVP
   Phase 1 MVP — KYC Manuel
   L'utilisateur upload une photo de sa CNI (recto-verso) et un selfie via l'app Flutter. Les fichiers sont chiffrés et envoyés sur S3. Un agent du back-office valide manuellement. Délai : 24-48h. Suffisant pour le lancement.
2. PH2
   Phase 2 — KYC Automatisé (Smile Identity)
   Intégration de Smile Identity (principal provider KYC pour l'Afrique). L'API analyse la CNI, extrait les données, et réalise une vérification biométrique (matching selfie/photo CNI). Délai : moins de 60 secondes. Taux d'automatisation : ~85%.
3. DRT
   Droits des données utilisateur
   L'utilisateur peut demander la suppression de son compte et de ses données (conformité RGPD / loi camerounaise sur la cybersécurité). La plateforme doit supporter cette opération avec archivage légal des données de transaction (obligation de rétention fiscale).

Le back-office est l'outil de pilotage interne de Hola Africa. Il doit permettre à l'équipe de support de résoudre chaque incident en moins de 5 minutes, sans intervention d'un développeur.

Job de réconciliation automatique

Chaque nuit à 2h00, un job automatique (cron NestJS) analyse les transactions PAID qui n'ont pas été provisionnées depuis plus de 2 heures. Il tente un re-provisionnement ou déclenche un remboursement automatique. Le matin, l'équipe finance reçoit un rapport récapitulatif.

Métriques critiques à surveiller

SLA & Disponibilité par service