Building robust client-server systems is straightforward. Building offline-first databases that synchronize reliably across unreliable network towers is a deep engineering challenge.
In emerging markets, mobile data connectivity is inconsistent. A rider may start their route with a 4G connection, lose signal entirely when dropping bottles in a basement supermarket, and regain 3G connection two hours later. If our application relied on standard HTTP REST requests to verify transactions, the rider would be unable to complete deliveries or track bottles during signal drops.
The Sync Queue Architecture
To solve this, our engineering team implemented a local synchronization queue on top of a SQLite database. Instead of making direct server mutations, the client application executes all mutations locally first, creating a serialized transaction package in a local outbox queue.
Client Action (Confirm Delivery)
│
▼
Execute Local SQLite Transaction (Instant UI feedback)
│
▼
Serialize Mutation & Append to Outbox Queue
│
▼
[Network Check]
├── Connected? ──► Send Outbox Queue (FIFO) ──► Reconcile on Server
└── Offline? ──► Sleep and Wait for Signal Event Listener
Conflict Resolution & Idempotency
A major risk in offline synchronization is double-submissions or stale updates. What if a rider logs a cash payment offline, and in the meantime, the plant manager manually updates the account balance from the web dashboard?
We resolved this by adopting a **Version-Stamped Event Stream** model:
- UUIDs: All transaction records generate a cryptographically secure UUID locally. This prevents primary key collisions when multiple offline devices sync to the server database.
- Vector Clocks: Every profile update is signed with an incrementing vector clock version. When syncing, the server compares the incoming clock version with the server version, resolving updates deterministically.
- Idempotent Endpoints: All backend API mutation routes check the transaction UUID. If the server receives a transaction it has already processed, it acknowledges the sync without executing the database write again.
Reliability Under Load
In production, our offline synchronization model has processed over 500,000 offline transactions without a single lockup or data corruption event. It allows riders to work freely, confident that their logs, collections, and work progress are perfectly preserved, regardless of mobile reception.
