offline-first

Offline-First Architecture

Apps that require internet to work lose 30%+ of users. These patterns make your app work everywhere — with or without connectivity.

Core principle: Local DB is source of truth

User Action → ViewModel → Repository
                               ↓
                         Local DB (Room)  ← single source of truth
                               ↓
                          UI observes Flow from Room
                               ↓ (background)
                         Network sync → update Local DB → UI auto-updates

Rule 1: Single-direction data flow — never mix local + remote in UI

// ✅ Repository: local DB is source of truth, network updates DB silently
class ItemRepositoryImpl @Inject constructor(
    private val itemDao: ItemDao,
    private val api: ItemApiService,
    @IoDispatcher private val dispatcher: CoroutineDispatcher
) : ItemRepository {

    // UI always observes local DB
    override fun getItemsStream(): Flow<List<Item>> =
        itemDao.getAll().map { it.map { entity -> entity.toDomain() } }

    // Sync pulls from network and updates local DB
    override suspend fun sync(): Result<Unit> = withContext(dispatcher) {
        runCatching {
            val remoteItems = api.getItems()
            itemDao.upsertAll(remoteItems.map { it.toEntity() })
        }
    }
}

// ✅ ViewModel triggers sync but observes local DB
@HiltViewModel
class HomeViewModel @Inject constructor(
    private val repository: ItemRepository
) : ViewModel() {

    val items: StateFlow<List<Item>> = repository.getItemsStream()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())

    init { sync() }

    fun sync() {
        viewModelScope.launch {
            repository.sync()   // updates DB → Flow auto-updates UI
        }
    }
}

Rule 2: Optimistic UI updates

// ✅ Apply change locally immediately, sync to server in background
override suspend fun toggleFavorite(itemId: String): Result<Unit> = withContext(dispatcher) {
    // 1. Update local DB immediately (UI updates instantly)
    val item = itemDao.getByIdOnce(itemId) ?: return@withContext Result.failure(NotFoundException())
    val newValue = !item.isFavorite
    itemDao.updateFavorite(itemId, newValue)

    // 2. Sync to server in background
    runCatching {
        api.patchItem(itemId, mapOf("is_favorite" to newValue))
    }.onFailure {
        // 3. Rollback local change if server fails
        itemDao.updateFavorite(itemId, !newValue)
    }
}