--- title: "Android Offline-First com Kotlin: Arquitetura em 2026 | Kotlin Brasil" url: "https://kotlin.dev.br/blog/android-offline-first-kotlin-2026/" markdown_url: "https://kotlin.dev.br/blog/android-offline-first-kotlin-2026.MD" description: "Aprenda a criar apps Android offline-first com Kotlin, Room, DataStore, WorkManager, Flow e sincronização segura para produção em 2026." date: "2026-05-20" author: "Karina Melo" --- # Android Offline-First com Kotlin: Arquitetura em 2026 | Kotlin Brasil Aprenda a criar apps Android offline-first com Kotlin, Room, DataStore, WorkManager, Flow e sincronização segura para produção em 2026. Construir um app Android que funciona bem apenas com internet perfeita é fácil. O desafio real aparece no ônibus, no elevador, no supermercado, no interior do Brasil, em redes corporativas instáveis ou quando o usuário abre o app com dados móveis fracos. É nesse cenário que a arquitetura **offline-first com Kotlin** deixa de ser luxo técnico e vira requisito de produto. Offline-first significa que a experiência principal do app parte do armazenamento local. A interface lê dados locais de forma reativa, grava alterações primeiro no dispositivo e sincroniza com o servidor quando houver rede confiável. Em vez de tratar cache como remendo, o app assume que conexão é uma dependência incerta. Essa mentalidade combina muito bem com Kotlin, [coroutines](/blog/coroutines-kotlin/), [Flow](/blog/kotlin-flow/), [Room](/tutoriais/kotlin-room-database-tutorial/), [DataStore](/glossario/serialization/) e WorkManager. Para quem busca vagas Android em 2026, dominar esse desenho também é um diferencial forte. Muitas empresas brasileiras têm apps usados em campo, logística, vendas, delivery, finanças, saúde, educação e operações internas. Nesses contextos, “mostrar erro de conexão” a cada instabilidade não é aceitável. ## O que offline-first realmente quer dizer? Um app offline-first não é apenas um app que “salva alguma coisa em cache”. Ele precisa ter uma regra clara para três perguntas: 1. de onde a tela lê os dados; 2. onde uma mudança do usuário é registrada primeiro; 3. como conflitos e falhas de sincronização são tratados. A resposta mais robusta costuma ser: a tela lê do banco local, a mudança é gravada localmente em uma fila de operações pendentes e a sincronização roda em background. O servidor continua sendo a fonte de verdade global, mas o dispositivo tem autonomia suficiente para manter a experiência utilizável. Essa diferença é importante. Um cache simples pode guardar a última resposta HTTP e expirar depois de alguns minutos. Offline-first vai além: o usuário consegue criar, editar, marcar, favoritar ou concluir ações mesmo sem rede, e o app sabe reconciliar essas ações depois. ## Arquitetura recomendada para Android com Kotlin Uma arquitetura prática pode seguir quatro camadas: - **UI com Compose ou Views** observando `StateFlow`; - **ViewModel** convertendo fluxos do domínio em estado de tela; - **Repository** decidindo entre banco local, rede e fila de sincronização; - **Data sources** para Room, DataStore, API HTTP e WorkManager. Se você já estudou [MVVM com Kotlin](/tutoriais/kotlin-mvvm-tutorial/) ou [Clean Architecture em Kotlin](/guias/guia-clean-architecture-kotlin/), a ideia é familiar. A diferença é que o repository não deve ser apenas um pass-through para Retrofit. Ele vira o ponto que protege o restante do app contra instabilidade de rede. Um fluxo comum fica assim: ```kotlin class TarefasRepository( private val dao: TarefaDao, private val api: TarefasApi, private val syncQueue: SyncQueue, ) { fun observarTarefas(): Flow> = dao.observarTodas() .map { entidades -> entidades.map { it.toDomain() } } suspend fun concluirTarefa(id: Long) { dao.marcarComoConcluida(id, sincronizada = false) syncQueue.enfileirar( OperacaoSync.ConcluirTarefa(id = id) ) } suspend fun sincronizarPendentes() { syncQueue.pendentes().forEach { operacao -> when (operacao) { is OperacaoSync.ConcluirTarefa -> { api.concluirTarefa(operacao.id) dao.marcarComoSincronizada(operacao.id) syncQueue.remover(operacao.idLocal) } } } } } ``` O ponto central é que a tela não espera a API responder para refletir a ação do usuário. Ela observa o Room; o Room muda imediatamente; a sincronização vem depois. ## Room como fonte local reativa Room continua sendo uma escolha muito natural para Android offline-first porque integra bem com SQLite, `Flow`, migrations e testes. Uma entidade offline-first normalmente precisa de metadados extras além dos campos de negócio. ```kotlin @Entity(tableName = "tarefas") data class TarefaEntity( @PrimaryKey val id: Long, val titulo: String, val concluida: Boolean, val atualizadaEm: Instant, val sincronizada: Boolean, val removidaLocalmente: Boolean = false, ) @Dao interface TarefaDao { @Query("SELECT * FROM tarefas WHERE removidaLocalmente = 0 ORDER BY atualizadaEm DESC") fun observarTodas(): Flow> @Query("UPDATE tarefas SET concluida = 1, sincronizada = :sincronizada WHERE id = :id") suspend fun marcarComoConcluida(id: Long, sincronizada: Boolean) @Query("UPDATE tarefas SET sincronizada = 1 WHERE id = :id") suspend fun marcarComoSincronizada(id: Long) } ``` Campos como `sincronizada`, `atualizadaEm` e `removidaLocalmente` parecem detalhes, mas evitam bugs difíceis. Sem eles, o app não sabe se uma linha veio do servidor, foi alterada localmente ou precisa ser removida depois que a API confirmar. Em projetos maiores, também vale separar entidades locais de DTOs da API. Não use a resposta HTTP como modelo de banco sem pensar. O servidor pode mudar nomes, omitir campos ou representar estados de uma forma ruim para consulta local. ## DataStore para preferências e estado pequeno Room deve guardar dados estruturados e consultáveis. DataStore entra melhor para preferências, flags e pequenos estados de sincronização: último sync bem-sucedido, usuário selecionado, filtros salvos, token de paginação ou configuração de tema. ```kotlin class SyncPreferences( private val dataStore: DataStore, ) { private val ultimaSyncKey = stringPreferencesKey("ultima_sync") val ultimaSync: Flow = dataStore.data.map { prefs -> prefs[ultimaSyncKey]?.let(Instant::parse) } suspend fun registrarSyncAgora(clock: Clock) { dataStore.edit { prefs -> prefs[ultimaSyncKey] = clock.now().toString() } } } ``` Evite colocar listas grandes em DataStore. Quando você perceber que precisa filtrar, ordenar, paginar ou relacionar dados, o lugar correto provavelmente é Room. ## WorkManager para sincronização confiável WorkManager é a peça certa para sincronização que precisa sobreviver a fechamento do app, reinício do aparelho e variações de rede. Ele não substitui coroutines no repository, mas resolve uma necessidade específica: executar trabalho adiado com restrições. ```kotlin class SincronizarTarefasWorker( context: Context, params: WorkerParameters, private val repository: TarefasRepository, ) : CoroutineWorker(context, params) { override suspend fun doWork(): Result = try { repository.sincronizarPendentes() Result.success() } catch (e: IOException) { Result.retry() } catch (e: HttpException) { if (e.code() in 500..599) Result.retry() else Result.failure() } } ``` Ao agendar, use restrições realistas: ```kotlin val request = OneTimeWorkRequestBuilder() .setConstraints( Constraints.Builder() .setRequiredNetworkType(NetworkType.CONNECTED) .build() ) .setBackoffCriteria( BackoffPolicy.EXPONENTIAL, 30.seconds.toJavaDuration() ) .build() WorkManager.getInstance(context).enqueueUniqueWork( "sync-tarefas", ExistingWorkPolicy.KEEP, request, ) ``` Use `ExistingWorkPolicy.KEEP` quando não quiser disparar várias sincronizações idênticas. Use `REPLACE` apenas quando a nova execução realmente deve cancelar a anterior. ## Estratégias de conflito Conflito acontece quando o mesmo dado muda no dispositivo e no servidor antes da sincronização. Ignorar esse problema é pedir bug intermitente. As estratégias mais comuns são: - **last write wins**: a alteração mais recente vence, simples mas perigosa; - **server wins**: o servidor prevalece, bom para dados sensíveis ou controlados; - **client wins**: o dispositivo prevalece, útil em rascunhos locais; - **merge por campo**: cada campo tem regra própria; - **resolução manual**: o usuário escolhe quando o conflito tem impacto real. Para muitos apps Android, uma combinação resolve bem: ações simples como “favoritar” usam last write wins; formulários importantes usam versão ou `updatedAt`; dados financeiros, médicos ou regulados devem favorecer o servidor e exibir mensagem clara. Mesmo este site não sendo YMYL, apps reais podem entrar em contextos sensíveis, então não trate sincronização como detalhe invisível quando a decisão afeta dinheiro, saúde ou segurança. ## Estado de tela: mostre a verdade sem assustar o usuário Offline-first não significa esconder tudo. O usuário precisa entender quando a ação foi salva localmente e quando ainda falta sincronizar. Um `UiState` pode carregar essa informação: ```kotlin data class TarefasUiState( val tarefas: List = emptyList(), val carregando: Boolean = true, val offline: Boolean = false, val pendentesSync: Int = 0, val mensagem: String? = null, ) ``` Na interface, prefira mensagens úteis: “Alteração salva neste aparelho. Vamos sincronizar quando a conexão voltar.” Isso é melhor que um erro genérico. Para operações críticas, deixe claro se a ação ainda não chegou ao servidor. Esse cuidado conversa com [Jetpack Compose](/guias/guia-jetpack-compose/) porque estado explícito torna a UI previsível. Em Compose, a tela apenas renderiza o estado atual; o ViewModel combina fluxos de dados locais, conectividade e fila pendente. ## Testes que valem a pena Testar offline-first exige cobrir cenários que muitas equipes esquecem: - usuário cria item sem internet; - app fecha antes da sincronização; - API retorna erro 500 e depois volta; - servidor rejeita operação com 409 Conflict; - migration preserva itens pendentes; - WorkManager não dispara workers duplicados; - tela mostra dados locais antes do refresh remoto. Use testes unitários no repository para regras de fila e testes instrumentados para Room quando necessário. Se o projeto já usa [JUnit 5 e MockK](/blog/kotlin-testes-junit5-mockk-guia/), simule API indisponível e confirme que o banco local continua correto. Para organizar essa cobertura em camadas, consulte também o [guia completo de testes em Kotlin](/guias/guia-testes-kotlin/), especialmente as partes de Flow, Android e CI. ## Erros comuns em apps offline-first O erro mais comum é chamar tudo de cache. Cache pode ser descartável; dado offline-first não pode. Se o usuário criou um registro local, aquilo precisa de durabilidade, status e estratégia de retry. Outro erro é sincronizar tudo em uma única chamada gigante. Isso dificulta retry parcial, aumenta risco de conflito e deixa o app frágil. Prefira operações pequenas, idempotentes quando possível, com identificadores locais e remotos bem definidos. Também evite espalhar lógica de rede pela UI. Quando cada tela decide se busca API, salva banco ou mostra cache, o comportamento fica inconsistente. Centralize no repository e faça a UI observar estado. Por fim, não esqueça observabilidade. Logs estruturados, métricas de falha de sync e contagem de operações pendentes ajudam a encontrar problemas reais em produção. Se o app depende de backend, vale estudar também [observabilidade em Kotlin](/blog/kotlin-observabilidade/) e [CI/CD para Kotlin](/guias/guia-kotlin-ci-cd/). ## Quando não usar offline-first completo? Nem todo app precisa do pacote inteiro. Um app de notícias pode resolver com cache de leitura e refresh manual. Um app bancário pode permitir consulta offline limitada, mas bloquear transações sem confirmação do servidor. Um app de entregas, por outro lado, provavelmente precisa fila local, geolocalização, retry e confirmação explícita. A pergunta prática é: o que o usuário precisa fazer quando a rede falha? Se a resposta for “continuar trabalhando”, offline-first merece arquitetura de primeira classe. ## Conclusão Android offline-first com Kotlin é uma combinação madura em 2026. Room oferece persistência local reativa, DataStore resolve preferências pequenas, WorkManager cuida de sincronização confiável, Flow mantém a UI atualizada e coroutines deixam o código assíncrono legível. O ponto mais importante é arquitetural: trate rede como detalhe instável, não como base da experiência. A tela deve depender do estado local; o repository deve coordenar banco, API e fila; a sincronização deve ser resiliente, observável e testável. Se você está montando portfólio, um app offline-first bem documentado vale muito mais que um CRUD que só funciona online. Ele demonstra maturidade de produto, conhecimento de Android real e capacidade de lidar com problemas que aparecem em produção. Para ampliar a visão além do mobile, vale comparar como Go é usado em backends leves que sincronizam dados com apps mobile. No Kotlin, a vantagem é construir a experiência Android e a camada de domínio com a mesma linguagem, mantendo segurança de tipos do banco local até a tela.