Build an Offline-First App

Phones lose signal in lifts, on rural roads, in school compounds with unreliable data, and during network outages. An app that shows a spinner or an error screen whenever the network drops feels broken, even when the user's own data is sitting safely on the device. An offline-first app works the other way round: it treats the local database as the source of truth, shows what it has immediately, and synchronises with the server when it can.

This lesson is the practical capstone of the data-layer lessons in the Modern Android App Architecture programme (https://developer.android.com/courses/android-architecture). It follows the official guide Build an offline-first app (https://developer.android.com/topic/architecture/data-layer/offline-first) and uses Room, Retrofit and WorkManager (https://developer.android.com/topic/libraries/architecture/workmanager).

By the end you will be able to:

• Explain offline-first and why the database is the source of truth.
• Choose read and write strategies, including queued writes.
• Design sync with WorkManager: constraints, retries, back-off and unique work.
• Pick a conflict resolution policy and understand its trade-offs.
• Monitor connectivity with a Flow.
• Show sync status honestly in the UI.
• Test the sync logic.

Big idea: the UI never waits for the network. It reads the database, and the network is just one of the things that updates the database.

Honesty note: version numbers are placeholders ("latest stable"). Room 3 imports are used, as in lesson 34; change them to androidx.room for Room 2.x. The server in this lesson is imaginary; the sync logic is real and testable with fakes.

• Room, DAOs and Flow (lesson 34).
• Repositories, data sources and error handling (lesson 62).
• UI state production (lesson 61).
• Retrofit (lesson 29).
• Coroutines and Flow (lesson 33).

Not just a cache

A cache speeds things up but the network is still in charge: if there is no cache entry, nothing shows. In an offline-first app, the database is complete enough to use on its own, and the network exists to keep it fresh and to send local changes upstream.

        ┌───────────────┐
        │      UI       │  reads ONLY from the repository
        └───────┬───────┘
                │ Flow
        ┌───────▼───────┐
        │  Repository   │
        └───┬───────┬───┘
   reads    │       │   writes (and a sync request)
        ┌───▼───┐ ┌─▼────────────┐
        │  DB   │ │ Sync worker  │──► Network
        │ (SSOT)│◄┤ (WorkManager)│◄── Network
        └───────┘ └──────────────┘

Why it is worth the effort

The cost is sync logic: you must reason about what happens when the server and the device disagree.

A teacher records attendance for each class. Requirements:

• It must work in a classroom with no network.
• Records are uploaded when a connection is available.
• The teacher can see which records are not yet uploaded.
• The server may also contain records entered by other teachers; they must appear.

Models and states

Each local record has a sync state:

enum class SyncState { SYNCED, PENDING_UPLOAD, FAILED }
@Entity(tableName = "attendance")
data class AttendanceEntity(
 @PrimaryKey val id: String, // client-generated UUID, so records can be created offline
 val studentName: String,
 val date: String, // ISO-8601 date
 val present: Boolean,
 val updatedAtMillis: Long, // used for conflict resolution
 val syncState: SyncState
)

Key design choices:

• Client-generated ids (UUIDs): an offline device cannot ask the server for an id. A UUID lets the client create records safely, and the server accepts them.
• updatedAtMillis: when the record was last edited, used to decide who wins in conflicts.
• syncState: a row in PENDING_UPLOAD is a change the server has not seen. The enum needs a type converter in Room (store the name as a string). In Room 3 this is a @ColumnTypeConverter; in Room 2.x it is @TypeConverter (see lesson 34).

class SyncStateConverters {
 @ColumnTypeConverter
 fun toString(value: SyncState): String = value.name
 @ColumnTypeConverter
 fun fromString(value: String): SyncState = SyncState.valueOf(value)
}

(Register it with @TypeConverters(SyncStateConverters::class) on the database class. Check the Room 3 documentation for the exact annotation names.)

The DAO

@Dao
interface AttendanceDao {
 @Query("SELECT * FROM attendance WHERE date = :date ORDER BY studentName")
 fun observeForDate(date: String): Flow<List<AttendanceEntity>>
 @Query("SELECT * FROM attendance WHERE syncState != 'SYNCED'")
 suspend fun pendingChanges(): List<AttendanceEntity>
 @Query("SELECT COUNT(*) FROM attendance WHERE syncState = 'PENDING_UPLOAD'")
 fun observePendingCount(): Flow<Int>
 @Upsert
 suspend fun upsert(item: AttendanceEntity)
 @Upsert
 suspend fun upsertAll(items: List<AttendanceEntity>)
 @Query("SELECT * FROM attendance WHERE id = :id")
 suspend fun find(id: String): AttendanceEntity?
 @Query("UPDATE attendance SET syncState = 'SYNCED' WHERE id IN (:ids)")
 suspend fun markSynced(ids: List<String>)
}

The UI reads only from the database:

interface AttendanceRepository {
 fun observeForDate(date: String): Flow<List<AttendanceRecord>>
 fun observePendingCount(): Flow<Int>
 suspend fun mark(studentName: String, date: String, present: Boolean)
 suspend fun syncNow(): Result<Unit>
}

class OfflineFirstAttendanceRepository(
 private val dao: AttendanceDao,
 private val api: AttendanceApi,
 private val syncScheduler: SyncScheduler,
 private val clock: () -> Long = System::currentTimeMillis,
 private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) : AttendanceRepository {
 override fun observeForDate(date: String): Flow<List<AttendanceRecord>> =
 dao.observeForDate(date)
 .map { list -> list.map { it.toModel() } }
 .flowOn(ioDispatcher)
 override fun observePendingCount(): Flow<Int> = dao.observePendingCount()
 // mark() and syncNow() follow
}

No network call appears in the read path. Screens appear instantly, from disk, whether or not the device is online.

When the teacher taps "present":

1. Write to the database immediately, marked PENDING_UPLOAD.
2. The UI updates at once because it observes the database.
3. Schedule a sync that uploads pending changes when a connection exists.

override suspend fun mark(studentName: String, date: String, present: Boolean) {
 withContext(ioDispatcher) {
 val id = "$date|$studentName" // stable id for one student on one date
 dao.upsert(
 AttendanceEntity(
 id = id,
 studentName = studentName,
 date = date,
 present = present,
 updatedAtMillis = clock(),
 syncState = SyncState.PENDING_UPLOAD
 )
 )
 }
 syncScheduler.requestSync()
}

The method returns as soon as the local write finishes, so there is no spinner, and the user cannot lose their work by walking out of coverage. The word queued means the database row itself is the queue: pending rows are the work to do.

A stable id ("$date|$studentName") means marking the same student twice on the same day updates one row rather than creating a duplicate. Choose ids that make your operations idempotent (safe to repeat). Idempotence is essential, because retries mean the server may see the same upload more than once.

Why WorkManager

WorkManager runs deferrable, guaranteed background work: it survives app restarts and device reboots, respects constraints (such as network availability) and retries with back-off. It is the recommended tool for sync. Do not use a bare coroutine, a Service you manage by hand, or GlobalScope: they die with the process.

Add the dependency (use the latest stable version; recent releases include the Kotlin extensions in the main artifact, older ones need work-runtime-ktx):

[versions]
work = "<latest stable>"
[libraries]
androidx-work-runtime = { group = "androidx.work", name = "work-runtime", version.ref = "work" }

The worker

class SyncWorker(
 appContext: Context,
 params: WorkerParameters,
 private val repository: AttendanceRepository
) : CoroutineWorker(appContext, params) {
 override suspend fun doWork(): Result {
 val outcome = repository.syncNow()
 return when {
 outcome.isSuccess -> Result.success()
 runAttemptCount < 5 -> Result.retry() // WorkManager applies back-off
 else -> Result.failure()
 }
 }
}

CoroutineWorker gives you a suspend doWork. Returning Result.retry() asks WorkManager to run it again later with exponential back-off. (Inside doWork the name Result means ListenableWorker.Result; the repository's Result<Unit> is Kotlin's. Import carefully or alias one of them.)

A word on constructor injection: WorkManager creates workers itself, so passing repository through the constructor needs a WorkerFactory (or Hilt's @HiltWorker, lesson 65). A simple manual factory:

class AppWorkerFactory(private val repository: AttendanceRepository) : WorkerFactory() {
 override fun createWorker(
 appContext: Context,
 workerClassName: String,
 workerParameters: WorkerParameters
 ): ListenableWorker? = when (workerClassName) {
 SyncWorker::class.java.name -> SyncWorker(appContext, workerParameters, repository)
 else -> null
 }
}

Register it by implementing Configuration.Provider in your Application class and returning a Configuration that uses the factory (the official WorkManager documentation shows the current form).

The scheduler

interface SyncScheduler { fun requestSync() }
class WorkManagerSyncScheduler(private val context: Context) : SyncScheduler {
 override fun requestSync() {
 val request = OneTimeWorkRequestBuilder<SyncWorker>()
 .setConstraints(
 Constraints.Builder()
 .setRequiredNetworkType(NetworkType.CONNECTED)
 .build()
 )
 .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
 .build()
 WorkManager.getInstance(context).enqueueUniqueWork(
 "attendance-sync",
 ExistingWorkPolicy.KEEP, // if a sync is already queued, do not queue another
 request
 )
 }
}

• Constraint: only run when the network is connected. WorkManager waits for it, even across reboots.
• Unique work with KEEP: twenty quick taps cause one upload, because the sync reads all pending rows.
• Back-off: if the server is down, retries become gradually less frequent.

You can also schedule a periodic pull so that the device receives other teachers' changes:

val periodic = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
 .setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.UNMETERED).build())
 .build()
WorkManager.getInstance(context)
 .enqueueUniquePeriodicWork("attendance-periodic", ExistingPeriodicWorkPolicy.KEEP, periodic)

(Periodic work has a minimum interval of 15 minutes. UNMETERED means Wi-Fi, which spares mobile data; choose what suits your users.)

A robust sync is push then pull: upload local changes first, then download the server's.

override suspend fun syncNow(): Result<Unit> = withContext(ioDispatcher) {
 runCatchingNetwork {
 // 1. PUSH: send everything pending
 val pending = dao.pendingChanges()
 if (pending.isNotEmpty()) {
 api.upload(pending.map { it.toDto() })
 dao.markSynced(pending.map { it.id })
 }
 // 2. PULL: fetch changes from the server and merge
 val remote = api.changesSince(lastSyncToken())
 mergeRemote(remote)
 saveSyncToken(remote.nextToken)
 }
}

Note: if the upload throws, nothing is marked as synced, so the next run re-uploads the same rows. That is why the server operation must be idempotent (upsert by id).

A careful detail: rows edited while the upload is in flight. If the user changes a row after pendingChanges() reads it but before markSynced runs, marking it synced would hide a newer change. Fix it by marking synced only if the row has not changed since:

@Query("UPDATE attendance SET syncState = 'SYNCED' WHERE id = :id AND updatedAtMillis = :version")
suspend fun markSyncedIfUnchanged(id: String, version: Long)

and calling it for each uploaded item with its updatedAtMillis. Otherwise the newer edit would never upload.

Conflict resolution

A conflict happens when the same record was changed on the device and on the server. You must pick a policy.

A simple last-write-wins merge, protecting local pending edits:

private suspend fun mergeRemote(remote: List<AttendanceDto>) {
 for (dto in remote) {
 val local = dao.find(dto.id)
 val keepLocal = local != null &&
 local.syncState == SyncState.PENDING_UPLOAD &&
 local.updatedAtMillis > dto.updatedAtMillis
 if (!keepLocal) dao.upsert(dto.toEntity(SyncState.SYNCED))
 }
}

Be honest about the limit: device clocks can be wrong, so timestamps are a heuristic. For data where silent loss matters, use server-assigned versions (an incrementing version or ETag) and have the server reject stale writes, then let the client re-fetch and retry or ask the user.

Deletes

You cannot simply delete a row if you need to tell the server. Use a tombstone: mark the row deleted = true, sync it, then really remove it after the server confirms.

Observing connectivity

Connectivity is a hint, not a guarantee (a device can be "connected" to Wi-Fi with no internet). Still, it is useful for showing a banner. Observe it as a Flow:

class ConnectivityObserver(context: Context) {
 private val manager = context.getSystemService(ConnectivityManager::class.java)
 val isOnline: Flow<Boolean> = callbackFlow {
 val callback = object : ConnectivityManager.NetworkCallback() {
 override fun onAvailable(network: Network) { trySend(true) }
 override fun onLost(network: Network) { trySend(false) }
 }
 manager.registerDefaultNetworkCallback(callback)
 trySend(manager.activeNetwork != null)
 awaitClose { manager.unregisterNetworkCallback(callback) }
 }.distinctUntilChanged()
}

(This needs the ACCESS_NETWORK_STATE permission in the manifest.)

Telling the user the truth

data class AttendanceUiState(
 val records: List<AttendanceRecord> = emptyList(),
 val pendingCount: Int = 0,
 val online: Boolean = true
)
class AttendanceViewModel(
 repository: AttendanceRepository,
 connectivity: ConnectivityObserver,
 private val date: String
) : ViewModel() {
 val uiState: StateFlow<AttendanceUiState> = combine(
 repository.observeForDate(date),
 repository.observePendingCount(),
 connectivity.isOnline
 ) { records, pending, online -> AttendanceUiState(records, pending, online) }
 .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), AttendanceUiState())
}

@Composable
fun SyncBanner(pending: Int, online: Boolean) {
 val text = when {
 pending > 0 && !online -> "$pending changes saved on this phone. They will upload when you are online."
 pending > 0 -> "Uploading $pending changes…"
 !online -> "Offline. Showing saved data."
 else -> return
 }
 Surface(color = MaterialTheme.colorScheme.secondaryContainer, modifier = Modifier.fillMaxWidth()) {
 Text(text, Modifier.padding(12.dp), style = MaterialTheme.typography.bodyMedium)
 }
}

The words matter. "Saved on this phone" reassures the teacher that nothing is lost; "Offline" without more would worry them.

Because the sync logic is in the repository and the database and API are replaceable, you can test it with fakes:

class SyncTest {
 private val dao = FakeAttendanceDao()
 private val api = FakeAttendanceApi()
 private val scheduler = object : SyncScheduler { var calls = 0; override fun requestSync() { calls++ } }
 @Test
 fun mark_saves_locally_as_pending_and_requests_sync() = runTest {
 val repo = OfflineFirstAttendanceRepository(dao, api, scheduler, { 1_000 }, StandardTestDispatcher(testScheduler))
 repo.mark("Ada", "2026-10-26", present = true)
 val row = dao.find("2026-10-26|Ada")!!
 assertEquals(SyncState.PENDING_UPLOAD, row.syncState)
 assertEquals(1, scheduler.calls)
 }
 @Test
 fun failed_upload_keeps_rows_pending() = runTest {
 api.failUploads = true
 val repo = OfflineFirstAttendanceRepository(dao, api, scheduler, { 1_000 }, StandardTestDispatcher(testScheduler))
 repo.mark("Ada", "2026-10-26", true)
 val result = repo.syncNow()
 assertTrue(result.isFailure)
 assertEquals(SyncState.PENDING_UPLOAD, dao.find("2026-10-26|Ada")!!.syncState)
 }
 @Test
 fun newer_local_edit_survives_older_remote_copy() = runTest {
 dao.upsert(AttendanceEntity("d|Ada", "Ada", "d", true, updatedAtMillis = 2_000, syncState = SyncState.PENDING_UPLOAD))
 api.remote = listOf(AttendanceDto("d|Ada", "Ada", "d", present = false, updatedAtMillis = 1_000))
 val repo = OfflineFirstAttendanceRepository(dao, api, scheduler, { 3_000 }, StandardTestDispatcher(testScheduler))
 repo.syncNow()
 assertTrue(dao.find("d|Ada")!!.present)
 }
}

To test the worker itself, the androidx.work:work-testing artifact provides TestListenableWorkerBuilder, which runs doWork directly and lets you assert on Result.success(), Result.retry() and Result.failure(). On a device, adb shell cmd connectivity airplane-mode enable (on supported versions) or the emulator's network controls let you try the full flow: mark attendance offline, watch the banner, turn the network on, and watch the pending count drop to zero.

Mistake #1: Reading from the network in the UI path. Fix: the UI reads only from the database.

Mistake #2: Waiting for the server before showing a write. Fix: write locally first, then sync.

Mistake #3: Server-assigned ids for offline-created records. Fix: use UUIDs or deterministic keys.

Mistake #4: Non-idempotent uploads. Fix: upsert by id on the server.

Mistake #5: Using a coroutine or service instead of WorkManager. Fix: use WorkManager with constraints.

Mistake #6: Deleting local data when a refresh fails. Fix: change data only after success.

Mistake #7: Marking rows synced after concurrent edits. Fix: compare versions.

Mistake #8: Trusting device clocks completely. Fix: prefer server versions where loss matters.

Mistake #9: Hiding sync state from users. Fix: show pending counts and clear wording.

Mistake #10: Queuing a new job for every tap. Fix: unique work with KEEP.

Question 1. What is the difference between a cache and an offline-first design?

Question 2. Why does enqueueUniqueWork with KEEP help?

Question 3. What is idempotence and why does sync need it?

Question 4. Name two conflict policies and a risk of each.

Question 5. Which WorkManager feature delays work until the network is available?

Go deeper: official resources

• Modern Android App Architecture programme
• Build an offline-first app
• Data layer
• Recommendations for Android architecture