Most retail software in Africa is built somewhere else and translated. It assumes a fast, always-on internet connection, a US-quality power grid, and a customer base that is fine if the app spins for three seconds. In Kigali, all three assumptions break before lunch. Offline-first isn't a feature — it is a precondition for retail software to even be considered.
What 'offline-first' is actually not
When a vendor says 'we work offline,' nine times out of ten what they mean is: the app caches a few static screens, and as soon as you try to do anything that matters — record a sale, look up a balance, print a receipt — it shows a sad cloud icon and asks you to reconnect. That isn't offline-first. That is offline-cosmetic.
- Offline-first means writes happen locally, instantly, the same as online.
- Offline-first means the database lives on your device, not in someone's data centre.
- Offline-first means when the internet returns, everything syncs without you noticing — and without losing or duplicating a single sale.
“If your software can't take a sale while the wifi router is unplugged, it isn't software. It is a marketing brochure.”
The three things that have to work offline
We built Iwange around three non-negotiable offline operations. If even one of them is missing, retailers lose trust in the system and stop using it — which is the only thing worse than not having it.
- Quick Sell. Every sale recorded, receipted, totalled, locally and instantly. No spinner. No 'try again.'
- Stock lookup. Cashier needs to know if you still have the item. The latest stock view has to be on the device, not in the cloud.
- Customer credit (amadeni). Lookups and new credit entries — both work offline. The customer is standing right there, you cannot say 'please come back when the internet returns.'
How we make this safe
The hard part of offline-first isn't writing locally — it's syncing safely. Two cashiers can ring up the same item from two different devices, the internet returns, and now there's a conflict. Most cloud POS products handle this badly. We handle it three ways at once.
- Every mutation gets a client-generated idempotency key, so a retry never creates a duplicate sale.
- An outbox queue drains in strict FIFO order once you're online, so the server sees events in the same order they happened in the shop.
- Critical conflicts — like two cashiers editing the same item's stock — surface a small side-by-side diff. The owner decides. No silent overwrites.
Iwange uses Dexie.js over IndexedDB for the local database, Workbox for the service worker, and a tiny backend middleware that recognises idempotency keys. Three open-source tools, one design choice: the cloud is optional, never required.
The cost of getting this wrong
If your POS is online-only and your shop has a four-minute power cut in the middle of Saturday lunch rush, you've just lost between 12 and 30 sales. Not delayed — lost. Customers don't wait for your laptop to reboot. They walk to the next shop. We saw this happen in two of our pilot shops before we hardened the offline path. Both stopped trusting any software at all until we rebuilt the sync engine from scratch.
Offline-first is not a feature you bolt on. It is a design choice you make on day one, baked into every read and write. In African retail, anything less is a product that works in the demo and fails in the shop.
Reported and written by the Iwange team in Kigali. We do not publish individual bylines — what gets printed here was observed at a counter and checked twice before it ran.