Offline sync core §1
Offline operation is mandatory
Maricopa already documents procedures for operating SiteBook and printer functions in an offline mode when cellular or VPN connectivity is lost. A platform that sits on top of that environment therefore must not become the weak link that says “No internet. App unavailable.”
The write path
LOCAL EVENT CREATED QUEUED SYNC ATTEMPTED SERVER RECEIVED RECEIPT ISSUED ACKNOWLEDGED
Six states, in the blueprint’s order, plus the failure state — because the interface has to be able to tell the truth about failing as well as about succeeding.
SYNC ERROR Sync error — supervisor notified
| State | What the worker is told | Where the record is |
|---|---|---|
LOCAL_EVENT_CREATED |
Saved on this device only | Held on the device |
QUEUED |
Queued for sync | Held on the device |
SYNC_ATTEMPTED |
Sync attempted | Held on the device |
SERVER_RECEIVED |
Received by county command | Confirmed by the server |
RECEIPT_ISSUED |
LockChain receipt issued | Confirmed by the server |
ACKNOWLEDGED |
Acknowledged | Confirmed by the server |
The three held states and the three confirmed states are decided by
syncTone() in the engine, not by a class name typed into a template. A state added to the
engine arrives on this page already carrying the correct treatment.
The point of this page
A yellow mark must never look like a green one
“A yellow ‘saved locally’ checkmark must never be visually indistinguishable from a green ‘received by county command’ acknowledgement.”
These are two entirely different facts about a worker’s evening. One says the record exists on a tablet in their hand. The other says the county has it. If a tablet is lost, dropped or wiped between those two states, the difference between them is the difference between a documented incident and an incident nobody outside that room ever knew about.
Held on the device
SAVED ON THIS DEVICE ONLY
Amber. Dashed border. Square dot. The county has not seen this yet, and nothing about the chip suggests otherwise.
Confirmed by the server
RECEIVED BY COUNTY COMMAND
Green. Solid border. Round dot. A LockChain receipt exists and can be produced.
Three differences, not one. Colour, border style and dot shape all change together. That is deliberate: a worker with a colour-vision deficiency, a tablet in direct desert sun, a screenshot printed in monochrome, or a screen with a failing backlight must all still be able to tell the two apart. A distinction that exists only in hue is a distinction that disappears under the exact conditions a field device is most likely to be used in.
The interface should always tell the truth
Saved on this device is not the same fact as received by county command.
Carried locally, encrypted
What the field application holds when the network is gone
The enumerated local subset. It is a working set, not a copy of the county’s systems: it is what a person at one location needs in order to keep working for the rest of a shift.
- current assignments
- current procedures / checklists
- location / election configuration
- permitted asset references
- open tasks
- locally created incidents
- locally created evidence metadata
- pending custody events
- emergency procedures
Writes become events. The event is created locally, queued, attempted, received, receipted and acknowledged — and the worker can see which of those has actually happened at any moment.
Status strings
Honest, and specific enough to act on
ONLINE
Connected, and the queue is empty.
DEGRADED
Reachable, but not reliably. Writes still succeed locally.
OFFLINE — n EVENTS WAITING TO SYNC
The count is shown because a number is a fact and “offline” on its own is not.
SYNCING
The queue is draining. Not finished.
SYNC ERROR — SUPERVISOR NOTIFIED
The failure is escalated by the app, not left for the worker to notice.
Why the queue is an event queue and not a draft folder
A locally created event is a real canonical event from the moment it is written. It carries its actor, the role that actor held at the time, the device, the location and the times it occurred and was recorded. What it does not yet carry is a server acknowledgement or a LockChain receipt — and that is precisely why neither of those fields is inside the event’s own hash. A field that legitimately changes after the device hashed the record cannot sit inside a hash whose entire job is to prove that nothing changed.
Replay is idempotent, so a tablet that reconnects twice does not produce the record twice. And when a synchronisation genuinely fails, the app escalates rather than displaying a quiet icon: SYNC ERROR — SUPERVISOR NOTIFIED. The worker at that location has a polling place to run. Noticing that a spinner never stopped is not their job.
The rule underneath all of it. The interface should always tell the truth. Not an optimistic version of the truth, not a reassuring approximation, and never a green tick standing in for a fact that has not happened yet.