Building an Offline-First Android App

"Offline-first" gets used loosely to mean "works without internet," but the actual architecture is more specific than that.

The core idea: local data is the source of truth

This is a meaningfully different shape from "cache the last API response and show that if offline" — it supports reading, writing, and even creating new data while offline, with sync reconciling things once connectivity returns.

The typical pattern

1. UI reads from Room (or another local database), via Flow for reactive updates.
2. A repository layer decides when to fetch from network and writes results into the local database — the UI never talks to the network directly.
3. A sync mechanism (WorkManager is the standard modern choice) runs in the background, pushing local changes up and pulling remote changes down, independent of whether the user currently has the app open.

class NotesRepository(private val dao: NoteDao, private val api: NotesApi) {
    fun getNotes(): Flow<List<Note>> = dao.getAll()
 
    suspend fun refresh() {
        val remoteNotes = api.fetchNotes()
        dao.insertAll(remoteNotes)
    }
}

The UI observes getNotes() continuously — it updates automatically whenever refresh() writes new data, without the UI layer needing to know a network call happened at all.

The hard part: conflict resolution

If the same record can be edited both offline (on-device) and elsewhere (another device, a web version, the server directly), you need an explicit strategy for what happens when both versions try to reconcile:

• Last-write-wins — simplest, but can silently discard a user's offline edit.
• Field-level merging — more complex, but avoids losing changes that don't actually conflict.
• Surface the conflict to the user — appropriate when silently picking a winner risks losing something the user would care about.

There's no universally correct choice here — it depends on how much a lost edit would actually matter for your specific app.

Why retrofitting this later is expensive

An app built assuming the UI reads directly from network responses has that assumption baked into a lot of code — screens, view models, error handling all built around "a network call either succeeds or shows an error." Converting that to "the UI always reads local data, which may or may not be freshly synced" touches most of those same places. This is exactly the kind of decision worth making explicitly at the start — see our Android architecture guide for how this fits into the bigger early-decisions picture.