Architecture field guide · Maduuka
Maduuka software architecture, from business operation to code
A two-speed reading of the Maduuka platform: first the work a business sees, then the technical choices that make it coherent, traceable, and resilient when connectivity is unreliable.
Jump to the technical reading
Start without jargon
Maduuka is one thread of work, from counter to report
Maduuka is a business management platform for shops, pharmacies, restaurants, hotels, and branch networks. It connects sales, stock, customers, operations, and finance instead of trapping them in separate tools.
In practice, a sale entered on the web or Android can contribute to an invoice, stock movement, payment record, and report. Access rights, the relevant branch, and audit evidence travel with the workflow. The point is not to display technology for its own sake; it is to give each team a dependable account of what is happening in the business.
Who uses the ecosystem?
- ManagementA consolidated view of sales, stock, staff, and performance.
- Managers and branchesLocal operations, transfers, teams, and availability alerts.
- Frontline staffCheckout, kitchen, reception, pharmacy, and daily work.
The mental model to keep
- 1Two entry doorsA web browser for management work and an Android app for mobile operations.
- 2One shared languageModules share the same customers, products, payments, movements, and business controls.
- 3A governed memoryPersistent data lives in a shared MySQL database, filtered by franchise and branch context.
- 4Recovery pathsAndroid can keep supported reads and mutations in Room, then synchronise when connectivity returns.
For students and technical readers
A modular architecture, not a pile of disconnected boxes
The diagram separates client surfaces, the HTTP / REST boundary, shared business services, and the data foundation. That separation helps answer a core architecture question: where should a rule live so it stays consistent no matter which channel is used?
1. Client surfaces and the API boundary
Web: native PHP layered service-repository application
- Responsive pages and operational panels
- Controllers, middleware, and request validation
- Services for transactions and cross-module workflows
- Repositories, DTOs, PDO, and parameterised queries
Android: MVVM + Clean Architecture + offline-first
- Jetpack Compose and ViewModels
- Use cases and repository interfaces
- Retrofit, OkHttp, Moshi, and JWT APIs
- Room as the local source of truth for supported reads
- OfflineMutationQueue, SyncWorker, WorkManager, and reconnect retry
The boundary is named accurately: Maduuka HTTP / REST API boundary, not a separate API Gateway product.
Route families and authentication
| Family | Route | Role |
|---|---|---|
| Web / session | /api/ | Authenticated web-application requests. |
| Mobile / JWT | /api/v1/ | Token-authenticated REST APIs for Android. |
| Authentication | /api/auth/ | Sign-in, token renewal, and identity operations. |
| Synchronisation | /api/v1/sync/ | Controlled delivery of queued mobile changes. |
| Restaurant | /api/v1/restaurant/ | Orders, KOT, kitchen, tables, and settlement workflows. |
2. The shared business core
The modules are not independent mini-products. They rely on shared services for users, roles, franchise context, permissions, subscriptions, audit, notifications, and transaction rules.
- Sales and POSCart, payment, invoice, receipt, and shifts.
- Stock and procurementProducts, batches, units, BOM, suppliers, movements, and transfers.
- RestaurantTables, orders, KOT, KDS, kitchen, delivery, and settlement.
- HotelReservations, rooms, guests, folios, charges, and night audit.
- PharmacyPatients, prescriptions, dispensing, batches, FEFO, and safety controls.
- FinanceChart of accounts, journals, general ledger, expenses, reconciliation, and reports.
- OrganisationHR, attendance, payroll, administration, reports, and management views.
- ControlsEFRIS / fiscalisation, audit, idempotency, permissions, and traceability.
3. Four flows worth studying
A useful architecture exercise is to follow one piece of data across modules. These are four representative paths in the documented system.
POS → stock → finance
Product → cart / order → payment → invoice → stock movement → stock balance → journal / report
Payment methods can include cash, mobile money, card, and credit where enabled. Records remain linked and auditable.
Restaurant → kitchen → stock
Table / order → KOT → kitchen station / KDS → prepare → billing → settlement → BOM-based stock movement
SSE or near-real-time streaming is represented for supported kitchen displays. Offline capability remains feature-specific.
Hotel: reservation → folio
Reservation → availability → check-in → folio → room or restaurant charge → checkout → settlement → night audit
A restaurant charge may post to a guest folio; it does not automatically become cash before settlement under hotel checkout rules.
Pharmacy: prescription → dispensing
Patient / prescription → pharmacy POS → safety checks → cashier → dispenser → FEFO batch → audit → invoice / payment
Safety checks and controlled permissions make this different from an ordinary retail sale.
4. Data, operations, and honest boundaries
The current documented foundation is intentionally legible: a PHP web runtime, one shared MySQL instance, and file / export services. Control mechanisms are part of the architecture, not a footnote.
Persistent data
Shared MySQL with tenant-scoped data, foreign keys, transactions, views, stored procedures, and franchise_id validation.
Operations
Application and audit logs, metrics, scheduled tasks, migrations, backups, and recovery processes.
Files and outputs
Uploads, PDFs, CSV / spreadsheet exports, thermal receipts, and email when configured.
Future extensions
Mobile-money gateways, card gateways, SMS, Redis, read replicas, and load balancing remain future / deployment options, not the current core.
What offline-first actually means
Android does not make every action available offline. For supported features, Room acts as the local source of truth, a durable mutation enters OfflineMutationQueue, and SyncWorker / WorkManager attempts delivery. Responses—success, retryable failure, conflict, or validation failure—are recorded for recovery and review. Online-only actions remain deliberately gated.
Maduuka
See the architecture in use
Move from the model to Maduuka's screens and workflows.