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 secure.
Jump to the technical readingStart 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.
- 4One API contractWeb and Android go through the same protected HTTP / REST boundary, so business rules are enforced once.
For students and technical readers
A modular architecture, not a pile of disconnected boxes
The architecture 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
- Jetpack Compose and ViewModels
- Use cases and repository interfaces
- Retrofit, OkHttp, Moshi, and JWT APIs
- Room for on-device storage
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. |
| 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 (integrated on client request), 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.
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.
Offline on Android, always consistent
The Web application works online. The Android app keeps sales and daily work on the phone when the network drops, then sends them; every transaction is validated again and saved through the protected API so that stock, payments, and audit trails stay consistent across every device.
Maduuka
See the architecture in use
Move from the model to Maduuka's screens and workflows.