Offline-first is an architecture, not a feature flag

Most systems described as "offline-capable" are online systems with a cache bolted on. They work when the network is slow. They fall over when it is absent for six hours, which on a Zambian intercity corridor is a Tuesday.

The distinction matters because offline-first is not a feature you add near the end of a project. It is a constraint that reshapes the data model, the payment flow and the synchronisation protocol. If you adopt it late, you rewrite all three.

The seat inventory problem

An intercity bus has fifty-one seats. Six agents at four depots can sell them, plus the passenger app. If any of those can go offline, you cannot hold a single authoritative counter and check it before every sale — the check is exactly what is unavailable.

The approach that survived contact with reality was allocation rather than locking. Central inventory hands each agent a block of seats they may sell without consulting anyone. An agent holding eight seats can sell eight seats through a six-hour outage, because those seats are already theirs. Reconciliation on reconnect is then a merge of disjoint sets, not a conflict resolution problem.

Allocation sizes are the interesting parameter. Too small and agents run dry during outages. Too large and the app shows a bus as full when thirty seats are sitting unsold in a depot that has not connected since morning. We size the block from that agent's historical sales rate for that route and time of day, and rebalance whenever anyone reconnects.

Money is harder than seats

A seat can be double-sold and recovered from — someone gets bumped to the next departure and a refund. A payment that is taken twice is a different category of problem.

Every financial operation in the field apps carries a client-generated idempotency key that survives app restarts, device swaps and the agent trying again because the screen did not update. The server treats a repeated key as the same operation and returns the original result. This sounds obvious written down; it is routinely absent from systems that were designed online-first and retrofitted.

Mobile money adds its own wrinkle. The provider is a third party who may be reachable when you are not, or the reverse. We treat every mobile money collection as a two-phase operation with an explicit reconciliation pass, and we assume any individual confirmation may arrive minutes or hours late, out of order, or twice.

What you give up

Offline-first costs you real-time global consistency, and you should be honest with the business about that. A command center dashboard showing "seats sold" is showing seats sold that head office knows about. During a widespread outage that number lags reality, sometimes by hours.

The fix is not to hide the lag but to display it. Our dashboards show last-sync time per depot, and operations staff learned to read it within a week. A number with a known staleness is far more useful than a number that is silently wrong.

The test that matters

We run a monthly exercise where a depot is disconnected for a full trading day without warning to the staff. Not a staging environment — a real depot, selling real tickets. It has caught more design defects than any amount of unit testing, because the failures that matter in this domain are not the ones you can imagine in advance.

If you are building for infrastructure that does not cooperate, run that test. What you learn in the first hour will change your architecture.