Offline-first Flutter for field agents

Offline support is usually retrofitted: an app is built against a live API, then a cache is bolted on when someone reports failures in the field. The result is an app that is online-first with an apology layer.

Write to the device, sync from the device

The inversion that makes offline work is simple to state: every user action writes to local storage first and returns immediately. The network is a background reconciler, never a blocking dependency of the UI.

That means each local record carries its own sync state — pending, syncing, synced, conflicted — and the UI is honest about it. A repayment collected offline should look collected, with a small marker that it has not reached the server yet.

Conflicts are a product decision

Last-write-wins is a decision, not a default. In collections, the safe rule is that the device never overwrites a server-side settlement; a conflict becomes a task in a supervisor's queue instead of a silent overwrite. Deciding this with the client, before writing the sync code, saves a rewrite.

Test the bad path first

Airplane mode is not a sufficient test. The interesting failures are partial: a request that reaches the server and times out on the response, a token that expires mid-sync, a device whose clock is wrong. Each of those deserves an integration test, because each of them will happen in a week of real field use.