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.

For owners, students, and engineers Grounded in Maduuka's documented architecture
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

  1. 1
    Two entry doorsA web browser for management work and an Android app for mobile operations.
  2. 2
    One shared languageModules share the same customers, products, payments, movements, and business controls.
  3. 3
    A governed memoryPersistent data lives in a shared MySQL database, filtered by franchise and branch context.
  4. 4
    One 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?

01

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

Route families and authentication
FamilyRouteRole
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.
02

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.

Identity · RBAC · franchise_id · subscriptions · audit
  • 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.
03

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.

01

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.

02

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.

03

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.

04

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.

04

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.