Building Offline-First Android Apps: Architecture and Sync Strategies

User Action
    ↓
ViewModel
    ↓
Repository
    ├── Local: Room (immediate write, immediate read)
    └── Remote: API (background sync, eventual consistency)
    
UI ← Flow from Room ← Always current, even offline

class TaskRepositoryImpl(
    private val taskDao: TaskDao,
    private val taskApiService: TaskApiService,
    private val syncManager: SyncManager
) : TaskRepository {
    
    // Returns Flow from Room — always current
    override fun observeTasks(): Flow<List<Task>> =
        taskDao.observeAllTasks().map { entities -> entities.map { it.toDomain() } }
    
    override suspend fun createTask(task: Task) {
        // 1. Write to local immediately (user sees it right away)
        val entity = task.toEntity(syncStatus = SyncStatus.PENDING)
        taskDao.insert(entity)
        
        // 2. Try to sync to server in the background
        syncManager.scheduleSyncIfNeeded()
    }
}

enum class SyncStatus {
    SYNCED,    // Matches server
    PENDING,   // Created locally, not yet sent to server
    MODIFIED,  // Modified locally, not yet synced
    DELETED    // Marked for deletion, not yet synced
}

@Entity(tableName = "tasks")
data class TaskEntity(
    @PrimaryKey val id: String,
    val title: String,
    val completed: Boolean,
    val syncStatus: SyncStatus = SyncStatus.SYNCED,
    val localModifiedAt: Long = 0
)

class SyncWorker(
    context: Context,
    params: WorkerParameters,
    private val taskRepository: TaskRepository
) : CoroutineWorker(context, params) {
    
    override suspend fun doWork(): Result {
        return try {
            taskRepository.syncPendingChanges()
            Result.success()
        } catch (e: Exception) {
            if (runAttemptCount < 3) Result.retry()
            else Result.failure()
        }
    }
    
    companion object {
        fun createSyncRequest(): OneTimeWorkRequest {
            return OneTimeWorkRequestBuilder<SyncWorker>()
                .setConstraints(
                    Constraints.Builder()
                        .setRequiredNetworkType(NetworkType.CONNECTED)
                        .build()
                )
                .setBackoffCriteria(
                    BackoffPolicy.EXPONENTIAL,
                    15, TimeUnit.MINUTES
                )
                .build()
        }
        
        fun createPeriodicSyncRequest(): PeriodicWorkRequest {
            return PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
                .setConstraints(
                    Constraints.Builder()
                        .setRequiredNetworkType(NetworkType.CONNECTED)
                        .build()
                )
                .build()
        }
    }
}

WorkManager.getInstance(context).enqueueUniquePeriodicWork(
    "task_sync",
    ExistingPeriodicWorkPolicy.KEEP, // Don't replace existing scheduled work
    SyncWorker.createPeriodicSyncRequest()
)

class TaskSyncService(
    private val taskDao: TaskDao,
    private val apiService: TaskApiService
) {
    suspend fun syncPendingChanges() {
        // 1. Push local changes to server
        val pending = taskDao.getByStatus(SyncStatus.PENDING)
        val modified = taskDao.getByStatus(SyncStatus.MODIFIED)
        val deleted = taskDao.getByStatus(SyncStatus.DELETED)
        
        pending.forEach { entity ->
            val dto = apiService.createTask(entity.toDto())
            taskDao.update(entity.copy(
                syncStatus = SyncStatus.SYNCED,
                id = dto.id // Server assigns canonical ID
            ))
        }
        
        modified.forEach { entity ->
            apiService.updateTask(entity.id, entity.toDto())
            taskDao.update(entity.copy(syncStatus = SyncStatus.SYNCED))
        }
        
        deleted.forEach { entity ->
            apiService.deleteTask(entity.id)
            taskDao.delete(entity.id)
        }
        
        // 2. Pull server changes
        val serverTasks = apiService.getTasks()
        taskDao.upsertAll(serverTasks.map { it.toEntity(syncStatus = SyncStatus.SYNCED) })
    }
}

localModifiedAt

serverModifiedAt

@Composable
fun SyncStatusBar(syncStatus: SyncStatus) {
    AnimatedVisibility(visible = syncStatus != SyncStatus.SYNCED) {
        Row(
            modifier = Modifier
                .fillMaxWidth()
                .background(Color(0xFF3A3A3A))
                .padding(horizontal = 16.dp, vertical = 8.dp),
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            Text(
                text = when (syncStatus) {
                    SyncStatus.OFFLINE -> "You're offline — changes saved locally"
                    SyncStatus.SYNCING -> "Syncing..."
                    SyncStatus.ERROR -> "Sync failed — will retry"
                    else -> ""
                },
                color = Color.White,
                fontSize = 12.sp
            )
        }
    }
}