Guide d'architecture · Maduuka
L'architecture logicielle de Maduuka, de l'activité au code
Une lecture en deux temps de la plateforme Maduuka : d'abord les opérations vécues par une entreprise, puis les choix techniques qui les rendent cohérentes, traçables et résistantes aux connexions instables.
Aller à la lecture technique
Pour commencer sans jargon
Maduuka est le même fil de travail, du comptoir au rapport
Maduuka est une plateforme de gestion d'entreprise pour les boutiques, pharmacies, restaurants, hôtels et réseaux de succursales. Elle relie les ventes, les stocks, les clients, les opérations et la finance au lieu de les enfermer dans des outils séparés.
Concrètement, une vente saisie sur le Web ou Android peut alimenter une facture, un mouvement de stock, un paiement et un rapport. Les droits d'accès, la succursale concernée et les traces d'audit accompagnent le parcours. L'objectif n'est pas de montrer de la technologie pour elle-même : c'est de donner à chaque équipe une version fiable de ce qui se passe dans l'entreprise.
Qui utilise l'écosystème ?
- DirectionVue consolidée des ventes, du stock, du personnel et des résultats.
- Responsables et succursalesPilotage local, transferts, équipes et alertes de disponibilité.
- Personnel opérationnelCaisse, cuisine, réception, pharmacie et tâches quotidiennes.
Le modèle mental à retenir
- 1Deux portes d'entréeUn navigateur Web pour les postes de gestion et une application Android pour les opérations mobiles.
- 2Un langage communLes modules partagent les mêmes clients, produits, paiements, mouvements et contrôles métier.
- 3Une mémoire gouvernéeLes données persistantes résident dans une base MySQL partagée, filtrée par le contexte de franchise et de succursale.
- 4Des chemins de repriseL'application Android peut conserver certaines lectures et mutations dans Room puis les synchroniser quand la connexion revient.
Pour les étudiants et lecteurs techniques
Une architecture modulaire, pas une collection de boîtes isolées
Le diagramme distingue les surfaces clientes, la frontière HTTP / REST, le cœur métier partagé et la fondation de données. Cette séparation aide à répondre à une question centrale en architecture : où une règle doit-elle vivre pour rester cohérente quel que soit le canal utilisé ?
1. Les surfaces et la frontière d'API
Web : application PHP native en couches service-repository
- Pages et panneaux responsives
- Contrôleurs, middleware et validation
- Services pour transactions et workflows inter-modules
- Repositories, DTO, PDO et requêtes paramétrées
Android : MVVM + Clean Architecture + offline-first
- Jetpack Compose et ViewModels
- Use cases et interfaces de repositories
- Retrofit, OkHttp, Moshi et API JWT
- Room comme source de vérité locale pour les lectures prises en charge
- OfflineMutationQueue, SyncWorker, WorkManager et reprise à la reconnexion
La frontière est nommée selon ce qu'elle est : une frontière HTTP / REST Maduuka, et non un produit API Gateway distinct.
Familles de routes et authentification
| Famille | Route | Rôle |
|---|---|---|
| Web / session | /api/ | Requêtes de l'application Web avec session authentifiée. |
| Mobile / JWT | /api/v1/ | API REST authentifiée par jeton pour l'application Android. |
| Authentification | /api/auth/ | Connexion, renouvellement et opérations liées à l'identité. |
| Synchronisation | /api/v1/sync/ | Livraison contrôlée des changements mobiles mis en file d'attente. |
| Restaurant | /api/v1/restaurant/ | Commandes, KOT, cuisine, tables et règlements du module restaurant. |
2. Le cœur métier partagé
Les modules ne sont pas des mini-produits indépendants. Ils s'appuient sur des services communs pour les utilisateurs, les rôles, la franchise, les droits, les abonnements, l'audit, les notifications et les règles de transaction.
- Ventes et POSPanier, paiement, facture, reçu et shifts.
- Stocks et achatsProduits, lots, unités, nomenclature, fournisseurs, mouvements et transferts.
- RestaurantTables, commandes, KOT, KDS, cuisine, livraison et règlement.
- HôtelRéservations, chambres, clients, folios, charges et clôture de nuit.
- PharmaciePatients, ordonnances, dispensation, lots, FEFO et contrôles de sécurité.
- FinancePlan comptable, journaux, grand livre, dépenses, rapprochement et rapports.
- OrganisationRH, présence, paie, administration, rapports et pilotage.
- ContrôlesEFRIS / fiscalisation, audit, idempotence, droits et traçabilité.
3. Quatre flux à étudier
Un bon exercice d'architecture consiste à suivre une donnée à travers plusieurs modules. Voici quatre parcours représentatifs du système documenté.
POS → stock → finance
Produit → panier / commande → paiement → facture → mouvement de stock → solde de stock → écriture / rapport
Les moyens de paiement peuvent inclure espèces, mobile money, carte et crédit selon l'activation. Les enregistrements restent liés et auditables.
Restaurant → cuisine → stock
Table / commande → KOT → station cuisine / KDS → préparation → facturation → règlement → mouvement de stock fondé sur la nomenclature
Le streaming SSE ou quasi temps réel est représenté pour les écrans cuisine pris en charge. Le chemin hors ligne reste spécifique aux fonctions.
Hôtel : réservation → folio
Réservation → disponibilité → arrivée → folio → charge de chambre ou de restaurant → départ → règlement → clôture de nuit
Une charge de restaurant peut être portée au folio client ; elle ne devient pas automatiquement un encaissement avant le règlement selon les règles de sortie.
Pharmacie : ordonnance → dispensation
Patient / ordonnance → POS pharmacie → contrôles → caisse → dispensation → lot FEFO → audit → facture / paiement
Les contrôles de sécurité et les droits sur les produits sensibles rendent ce parcours différent d'une vente ordinaire.
4. Données, exploitation et limites honnêtes
La fondation actuelle documentée est volontairement lisible : un runtime Web PHP, une instance MySQL partagée et des services de fichiers / exports. Les mécanismes de contrôle font partie de l'architecture, pas d'une note de bas de page.
Base persistante
MySQL partagé avec données tenant-scoped, clés étrangères, transactions, vues, procédures stockées et contrôles par franchise_id.
Opérations
Journaux applicatifs et d'audit, métriques, tâches planifiées, migrations, sauvegardes et processus de reprise.
Fichiers et sorties
Téléversements, PDF, exports CSV / tableurs, reçus thermiques et e-mails lorsque configurés.
Extensions futures
Passerelle mobile money, passerelle carte, SMS, Redis, réplicas et load balancer restent des options futures / de déploiement, pas le cœur actuel.
Ce que signifie réellement offline-first
Android ne rend pas chaque action disponible hors ligne. Pour les fonctions prises en charge, Room sert de source locale, une mutation durable entre dans OfflineMutationQueue, puis SyncWorker / WorkManager tente la livraison. Les réponses — succès, erreur réessayable, conflit ou erreur de validation — sont enregistrées pour permettre une reprise et une revue. Les actions uniquement en ligne restent volontairement bloquées.
Maduuka
Voir l'architecture en usage
Passez du modèle aux écrans et aux workflows de Maduuka.