A dispatcher runs a fleet of trucks from a WhatsApp group and a whiteboard. Fuel is tracked on paper. A technician in Bosaso can be out of signal for a whole working day.
Global field service tools assume a steady network, card terminals and English. Here, offline is the normal operating mode, customers pay by mobile money, and many technicians read Somali first. ZilaFSM is in design: the design pack is complete and the first backend is ready to port. This is the design, decision by decision.
Offline is the default
Down-sync replicates from Postgres to the phone through PowerSync. Up-sync posts batches to Laravel, so every business rule stays on the server. A phone can work for fourteen days without a connection, and the sync is tested at seventy-two hours offline.
| Turned down | Why not |
|---|---|
| A hand-built sync protocol on MySQL | Four to eight engineer-weeks before the first job syncs. |
| Realm | Discontinued. |
| RxDB | The free storage tier stops at 500 documents. |
| ElectricSQL | Reads only. Writes would still be ours to build. |
| TanStack Query alone | A cache, not a sync. |
The cost is a vendor on the down-sync path, and we wrote that down.
Four rules for every column
Conflicts are designed out before they are resolved. Every column in the schema is assigned one of four rules.
| Data | Rule |
|---|---|
| What a technician creates | Appended as new rows: time, photos, notes, signatures. Inserts never conflict, which removes roughly 80% of conflicts. |
| What a dispatcher owns | The server always wins. |
| Shared fields | Last write wins, per column, by each column’s own update time. |
| Status changes | Replayed as named intents, such as “complete”, never as a raw value. The server checks the rules again. |
CRDTs were the obvious alternative. They add overhead per character and a large native dependency, and they cannot carry a business rule.
You cannot express “cannot complete a job with an unsigned worksheet” in a merge function.
An outbox that sends once
- Queue on the phone
Each change waits in a local table. Its id, made when it is queued and never when it is sent, doubles as its idempotency key.
- Push in batches
Twenty to fifty changes at a time, committed per job, so one poisoned job never stalls the rest.
- Apply once
The server records the key in the same transaction that applies the change. A phone that sends twice is counted once.
- Answer each change
Applied, conflict, or rejected with a reason. A refusal for validation or permission is final and never retried.
- 01worksheetapplied
- 02photoapplied
- 03notesconflict · server value kept, phone told
- 04completerejected · job already closed
Pulls use an opaque, signed cursor ordered by a server version that only goes up, never by update time, and run at repeatable read so a row committed mid-pull is never missed. A cursor that has gone stale gets a full resync.
Scope, visits and money are separate
A request is first checked for duplicates: the same site and asset with an open request in the last 48 hours. Then it becomes a work order. The work order is the scope, not the schedule. Visits are appointments under it, and payments have their own ledger, so each has its own state.
| Appointment | Moves through |
|---|---|
| Planned | Unscheduled, scheduled, dispatched. |
| Out in the field | Travelling, on site, work complete. |
| Paused | Waiting for parts, the customer or access. |
| Could not work | No access or customer absent, then needs reschedule. |
Dispatch enforces hard constraints, and a violation blocks the assignment. An expired certification can be overridden only by a manager, and the override is audited. The working week is Sunday to Thursday, and no Monday-to-Friday default ships. The first release enforces only two constraints, an active technician and no overlapping visits, because a bad optimiser is worse than none.
Stock is a ledger
Every stock change is an appended movement. The quantity on hand is checked against the ledger every night, and a mismatch means a bug, not a correction. Parts are reserved at dispatch, not when the work order is created, because early reservations strand stock. A reservation expires after seven days.
- 08:10receiptwarehouse +10
- 08:40transferwarehouse → van 3 · 3
- 14:20consumevan 3 → work order · 1
- 02:00checkledger 9 = on hand 9 ✓
Mobile money, assumed lost
The technician enters the customer’s number, the provider prompts the customer, and the customer confirms. Every webhook is assumed lost, so pending payments are polled at 30 seconds, 2 minutes, 10 minutes, an hour, then hourly for a day. The idempotency key is stored before the outbound call. Paid is not settled. With no signal, the fallback is cash or a payment link.
Somali first, and tenants apart
The Somali glossary is written with at least five technicians and two dispatchers, and frozen before any screen copy exists. Interfaces follow the words people already use, not the other way round.
Tenants share one database, held apart four times over: a global scope in the code, row-level security in Postgres, the tenant taken from the token and never from the request body, and cross-tenant tests on every endpoint that block a merge when they fail.
Notifications respect quiet hours unless a rule is marked urgent, and fall back from WhatsApp to SMS to a call task for the dispatcher. Every rule has a test, a simulation and a kill switch, and every send logs its cost.



