← All postsOffline-First on Android · Part 1 of 4

Offline-First on Android, Part 1 — Reads, Caching & Delta Sync

Two engineers working side by side at their laptops

How we made a smart-home app stop waiting for the network: one local source of truth, and a sync that pulls only what changed.

The problem

The app manages doors and the accessories around them (lights, sensors), and all of it syncs the same way; in this series, "device" means the user's phone or tablet, never the hardware in the house. For a long time the app had a steady tail of support reports that all said the same thing: "it doesn't work at my place."

Most of them were not bugs in the usual sense. Nothing crashed, and the code was "correct." The app simply assumed it had a connection. Tap a button, a spinner appears, the network answers, the UI updates. That works until someone walks into an elevator, or lives in a house where the router is one wall too far from the garage. For a smart-home app, that is exactly where our users were standing.

Accounts also vary a lot in size. A household has a few doors; a property manager runs doors across several sites, and every door logs every open, close and status change. Re-downloading all of that on every refresh is slow on a good connection and hopeless on a bad one.

So the goal was not "works on the plane." Browsing cached data in airplane mode is the easy part, an afternoon's work. The hard part is the ugly middle: the connection that is technically there but useless (three-bar WiFi behind a captive portal that hangs every request), and two devices that both edited the same door offline and now disagree about reality. The goal was simpler to say and harder to build: the app never makes the user wait for the network to see or change their own data.

Our approach

We started with a stance, because every later decision needed something to fall back on:

The device's local database is the source of truth for the user's own actions. The server is a peer it syncs with — not an authority it asks permission from.

That is what offline-first meant on this project: the app runs on local data and treats the network as an enhancement, not a requirement. It is about making the user's own interactions instant, not about syncing 24/7 in the background; mixing those two up is how teams over-build. We knew the trade-off going in: you stop writing error handling and start writing merge logic. For a read-only feed that is rarely worth it. For something users edit, across devices, it almost always is.

What we expected to win was quieter than "works on the subway":

  • It feels instant. Reads come from disk, writes apply immediately. No spinner stands between the user and their own data.
  • Flaky networks stop causing failures. The worst a bad connection can do is delay a sync.
  • It is cheaper on everything. Fewer redundant requests mean less server load, less battery and less mobile data, which matters most for users on slow or metered connections.

The whole architecture fit on one diagram, and it held for the entire project. The UI only ever talks to the local database, and a single atomic transaction fans each write out to both the local truth and an outbox that syncs later.

The whole system on one page: the UI reads Room only, and one transaction writes the local truth and the outbox
The whole system on one page: the UI reads Room only, and one transaction writes the local truth and the outbox

The two arrows on the server box are the whole sync story: push is the outbox draining the device's writes up; pull is the delta-with-a-cursor bringing the server's changes down. This part is about the pull arrow. Parts 2 and 3 are about push.

We built it native-first: platform APIs only, no third-party sync framework, nothing beyond the plumbing the app already carried. A sync engine is core infrastructure. When it misbehaves at 2am you want code you can step through, not a dependency you can only version-bump.

Reads: the screen never talks to the network

The UI never reads from the network. It reads from the local database, and a separate layer keeps that database fresh. Our first version of that layer was a naive full fetch:

fun observeDoors(): Flow<List<Door>> = doorDao.observeAll()   // UI subscribes here, forever

suspend fun refreshDoors() {                                   // called opportunistically (error handling: see the real version below)
    val remote = api.getDoors()
    doorDao.upsertAll(remote.toEntities())
}

The screen collects observeDoors(). When refreshDoors() writes to Room, the Flow emits and the screen updates. That alone decoupled rendering from the network: kill the connection mid-session and nothing on screen even flinches, because it was never reading the network to begin with.

There is no magic in it, just codegen. A DAO method returning a Flow gets a compile-time implementation that verifies the SQL against the schema, maps rows to entities, and (the important part) observes the underlying tables: any write re-runs the query and emits a fresh list. (Any write to an observed table re-runs it, even one that leaves the result identical, so distinctUntilChanged() sits between the DAO and the screen.) Nobody calls "reload the screen"; you write to the database and the right screens update themselves. suspend keeps it off the main thread with no hand-rolled threading.

Pulling only what changed

The full fetch was fine for a household account. It stopped being fine as an account grew to many doors and accessories plus years of activity history, because every refresh re-downloaded what had not changed: it burned battery and data, churned the UI, and could not resume if it died mid-page.

We replaced it with a sync token, a "since" watermark. The client stores an opaque, server-issued cursor, asks "give me everything changed since this token," and gets back a compact delta plus a fresh token to persist.

suspend fun refreshDoors() {
    val since = syncMetaDao.cursor(DOORS)             // read the watermark from Room
    val delta = try {
        api.getDoors(since = since)                   // only what changed (network — OUTSIDE any tx)
    } catch (e: CancellationException) { throw e      // never swallow cancellation
    } catch (e: IOException) { return }               // offline/timeout is fine — the UI keeps reading Room
    db.withTransaction {                              // room-ktx: these three commit as ONE
        doorDao.upsertChanged(delta.changed.toEntities())  // custom @Query, NOT a stock @Upsert (below)
        doorDao.deleteConfirmed(delta.removedIds)          // server-confirmed deletions
        syncMetaDao.setCursor(DOORS, delta.nextCursor)     // watermark moves in the SAME transaction
    }
}

The sync token is the read-side mirror of the outbox: the outbox is how the device's truth reaches the server, the token is how the server's truth reaches the device.

The hard decisions and trade-offs

The cursor lives in Room, not DataStore. It sits in a small sync_metadata table in the same database as the data it describes, so "I applied this delta" and "I advanced the watermark" commit or roll back as one transaction. Had we parked it in DataStore or SharedPreferences, they would have been two independent stores that cannot share a transaction: a process kill in the sliver between the two writes desyncs them: either the cursor moves ahead of data we never stored, and those changes are skipped for good, or the data lands without the cursor, and the next sync applies the same delta again. Transactional watermarks went into Room; DataStore stayed for user settings.

The server mints the cursor, never the device clock. It is tempting to roll your own "since = the newest updatedAt I've seen." We did not, because client clocks are one of the most common ways multi-device sync quietly corrupts data. The cursor stays opaque and server-minted.

upsertChanged could not be a stock Room @Upsert. Skipping rows the user is in the middle of editing takes a hand-written @Query with a NOT EXISTS filter against the outbox. A plain upsert there lets the server delta overwrite unsynced local edits. Part 3 shows the query.

We bounded the cache. It is a cache, not an archive. A handful of doors logging every open, close and status change adds up to far more events than anyone will ever scroll through within a year or two of normal use, and a list that keeps all of them locally turns a scroll into a slideshow. We decided the working-set size up front, per door rather than per account: a recent slice of each door's events stays local, the rest page in on demand. The same logic applied to entities. A consumer account holds a handful of doors and their accessories, but the design had to survive the commercial tail, the property manager with doors across several sites, without a rewrite. So the long tail is a light skeleton (id, name, version), and the full row is hydrated on demand (a tap, a search), which keeps queries fast however large the account grows. A cache that never evicts is just a database that keeps getting slower.

Cached data is keyed to something stable across sessions and restarts. Scope cached entities to a runtime identifier that changes when the user switches context and you get collisions: a fresh, empty context that mysteriously shows another context's data because the key lined up. If a key can change while the underlying data does not, that collision will happen to someone.

The first sync is a bootstrap, not a giant delta. since = null is paginated, and progress is persisted so a killed process resumes at the last page (the same page loop serves an ordinary delta that grew large over weeks offline). Only the active working set is hydrated (the current space, the first screen of doors); the long tail stays as skeletons. On the heaviest accounts, that is the difference between a fast, progressive first launch and a full-screen spinner. We also planned for the cursor dying of old age: a device offline for months may present a cursor the server has already pruned. On an expired-cursor rejection (HTTP 410 Gone), the app clears the token and re-enters the same bootstrap flow instead of wedging. A bootstrap is also the one place where absence does mean deletion: it is a complete snapshot, not a delta, so once its last page has landed, every local row the snapshot did not mention, and that has no pending or in-flight op of its own, is deleted.

The outcome

  • Rendering no longer depends on the network. Dropping the connection mid-session changes nothing on screen; the worst a bad connection can do is delay a refresh.
  • A refresh downloads only what changed since the last cursor, not the whole account.
  • The heaviest accounts get a progressive first launch instead of a full-screen spinner, and a device that comes back after months offline re-bootstraps instead of getting stuck.

That was the local half. Everything so far assumed the device only ever reads the server's truth. The moment users started changing things offline, and expecting those changes to survive, sync exactly once, and reconcile when the server disagreed, we needed the other half of the machine. That is Part 2.

Stack & takeaways

Stack: Kotlin, coroutines and Flow, Room (Flow DAOs, withTransaction), OkHttp.

  • Decide who owns the truth before writing any sync code. "The device owns the user's own actions" answered most of our later questions for us.
  • The UI reads the database, never the network. Once that holds, a dropped connection is no longer a UI problem.
  • Pull deltas with an opaque, server-minted cursor, and store it in the same database as the data, so data and watermark commit together.
  • Bound the cache and key it to something stable. A cache that never evicts, or that keys on something that can change, fails slowly and then all at once.
  • Treat the first sync and an expired cursor as the same bootstrap path, and make it resumable.