Problem
Small-to-medium businesses in Malawi needed a way to issue tax-compliant electronic invoices through the Malawi Revenue Authority's (MRA) Electronic Invoicing System — but existing solutions were expensive, fragile, and didn't account for the unreliable connectivity that's common across the country. The backend needed to be the single source of truth for compliance, resilience, and multi-device coordination.
Architecture
The system uses a database-per-tenant multi-tenancy model — a master MongoDB database holds shared entities (organizations, users, subscriptions), while each onboarded organization gets its own isolated database for sales, inventory, terminals, and shifts. This ensures data isolation and makes per-org scaling straightforward.
Key architectural decisions:
- Service-layer pattern — routes delegate to service modules, keeping business logic testable and decoupled from HTTP concerns
- MRA adapter layer — all MRA API interactions (activation, confirmation, invoice submission, config sync) go through a centralized adapter with HMAC signing, server-time synchronization, and structured error handling
- Real-time event bus — Socket.IO broadcasts sales, stock changes, configuration updates, and shift events to all connected terminals in an organization
- Offline transaction pipeline — when MRA is unreachable, transactions are queued with cryptographic signatures and processed through a retry pipeline with duplicate reconciliation and expiration handling
Key Features
- Terminal onboarding — three-step activation, confirmation, and config-sync wizard that registers POS terminals with MRA
- Invoice submission — atomic invoice number generation with daily counters, MRA payload assembly, and duplicate retry logic
- Offline resilience — queued transactions with signature verification, automated retry processing, and expired receipt recreation
- VAT5 certificates — full CRUD, TIN/certificate lookup, quantity decrement on use, and revalidation against MRA
- Inventory management — stock transfers, adjustments, informal purchases, warehouse inventory, reorder alerts, and raw material conversion
- Shift management — open/close cash register sessions with per-shift reporting
- Ops admin center — organization listing, subscription management, payment logging, and health monitoring
- Role-based access — JWT auth with orgAdmin, cashier, and opsAdmin roles enforced at route and middleware level
- B2B controls — online-only enforcement for business-to-business transactions
Outcome
The backend serves as the compliance backbone for the entire Tengai POS ecosystem, powering both the PWA and native mobile clients from a single API surface. The offline-first architecture means businesses can continue operating during connectivity outages — with transactions automatically reconciled when service returns. The system is currently in pre-production hardening ahead of MRA certification.