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 sécurisées.

Pour les dirigeants, étudiants et ingénieurs Fondé sur l'architecture documentée de Maduuka
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

  1. 1
    Deux portes d'entréeUn navigateur Web pour les postes de gestion et une application Android pour les opérations mobiles.
  2. 2
    Un langage communLes modules partagent les mêmes clients, produits, paiements, mouvements et contrôles métier.
  3. 3
    Une 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.
  4. 4
    Un contrat d'API communLe Web et Android passent par la même frontière HTTP / REST protégée, de sorte que les règles métier sont appliquées une seule fois.

Pour les étudiants et lecteurs techniques

Une architecture modulaire, pas une collection de boîtes isolées

L'architecture 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é ?

01

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

  • Jetpack Compose et ViewModels
  • Use cases et interfaces de repositories
  • Retrofit, OkHttp, Moshi et API JWT
  • Room pour le stockage local sur l'appareil

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

Familles de routes et authentification
FamilleRouteRô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é.
Restaurant/api/v1/restaurant/Commandes, KOT, cuisine, tables et règlements du module restaurant.
02

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.

Identité · RBAC · franchise_id · abonnements · audit
  • 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 (intégrée sur demande du client), audit, idempotence, droits et traçabilité.
03

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é.

01

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.

02

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.

03

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.

04

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.

04

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.

Hors ligne sur Android, toujours cohérent

L'application Web fonctionne en ligne. L'application Android conserve les ventes et le travail du jour sur le téléphone quand le réseau coupe, puis les envoie ; chaque transaction est revalidée et enregistrée via l'API protégée afin que le stock, les paiements et les traces d'audit restent cohérents sur tous les appareils.

Maduuka

Voir l'architecture en usage

Passez du modèle aux écrans et aux workflows de Maduuka.