Offline-First Is a Data Model Decision, Not a Caching One

Every learning platform eventually meets the same requirement: the learner is on an aircraft, on a ship, in a training centre with hostile wifi, or on a metered connection they would rather not spend on video. They need the course anyway, and their progress needs to survive the trip.

We have built this repeatedly — aviation training for pilots and crew, university platforms, school communities spanning students, teachers and supervisors — and the pattern that fails is always the same one. Offline gets scheduled as a late milestone and scoped as caching: put a local database in front of the API, serve from it when the network is gone, and sync when it returns.

That project overruns. Not because caching is difficult, but because caching is not the problem.

The problem is reconciliation

The moment a device can accept a change while disconnected, you have a distributed system with concurrent writers and no coordination. Two devices, or a device and a web session, can modify the same record while neither can see the other. When both reconnect, something has to decide what the truth is.

There are only a few honest answers, and choosing between them is a product decision that engineers cannot make alone:

Last write wins. Simple, and silently destroys data. Acceptable for a preference. Not acceptable for anything a person spent effort on.

Server wins. Predictable, and throws away the learner's offline work — which is precisely the work the feature existed to protect.

Client wins. Protects the learner and lets a stale device overwrite newer truth, including administrative changes.

Merge. Correct, and only possible if the data model was designed for it.

Ask the user. Sometimes right, usually a confession that the model cannot decide, and unbearable if it happens often.

The reason "merge" depends on the model is worth being concrete about. Consider course progress. Modelled as a single field — progress: 60% — two devices produce two numbers and there is nothing to merge; you are back to picking a winner. Modelled as a set of completion events, one per lesson with a timestamp, the merge is a set union and the result is correct without anyone choosing. Same feature, same screen, and one version can reconcile while the other cannot.

That is the whole argument. Offline capability is decided when you choose between progress: 60% and a set of events — which is usually years before anyone writes the word "offline" on a roadmap.

Practical consequences for the model

Prefer append-only facts to mutable state. Events union cleanly. Counters and current-value fields conflict. Where the interface needs a current value, derive it.

Let the client mint identifiers. A device that has to wait for a server to issue an ID cannot create anything offline. Use a UUID generated on the device, carried through to the server unchanged, so an offline creation followed by an offline edit refers to the same thing and is not duplicated on sync.

Make writes idempotent. A sync will be interrupted mid-flight and retried. Every operation needs to be safe to apply twice, which means each carries a stable identity of its own — not just the record it touches.

Record when, on whose clock. Device clocks are wrong, sometimes by years, and users change them. Timestamps from a device are evidence, not authority. If ordering matters, carry a logical counter alongside the wall clock.

Decide per field, not per record. For an aviation training record, a learner's completion of a module is theirs and should win. The module's content and its validity dates are the operator's and should win. These live in the same document and need opposite policies.

Content is the easier half, and still not trivial

Bulk content — video, documents, scenario assets — has no conflict problem, since learners do not edit it. It has a size problem.

The questions that matter are about scope and lifecycle. Does the learner choose what to download, or does the platform decide? Both are defensible; what fails is downloading everything by default, which meets the app-store cellular limits and the device's storage limits at once.

Then: what happens when content is revised while an offline copy exists? A pilot studying a superseded procedure is a compliance incident, not a caching inconvenience. Content needs a version, the device needs to know which version it holds, and there has to be a defined behaviour — up to and including refusing to present material known to be withdrawn. In a regulated training context that behaviour is part of the audit story and needs to be written down before it is built.

And storage has to be reclaimable. Devices fill up, and an app that grows without bound gets deleted.

What sync should feel like

The interface principle that holds up: offline should be unremarkable, and sync should be visible without being a task.

The app should not gate the learner behind a connectivity check or make them press a sync button. It should also never lie — showing work as saved when it is queued locally is a promise that breaks when the device is lost. A small, permanent indication of what is not yet on the server, and a clear statement when reconciliation needed a decision, is enough. Silence is the wrong default in both directions.

The reason to decide early

None of this is expensive to build at the start. Choosing event-shaped data, client-generated identifiers and idempotent writes costs nothing at the beginning of a project.

Retrofitting them is a migration of live data, a rewrite of the API's write path, and a change to every client at once. That is the cost teams actually pay, and they pay it because offline looked like a feature rather than a property of the data model.

If a platform will ever need to work without a connection — and a training platform always will — the cheapest moment to decide is before the first table exists.

---

iLeaf builds learning platforms for aviation, higher education, schools and professional training, with fifteen years of mobile and backend delivery behind them. See the work or start a conversation.