Offline-First Repositories and Synchronization

Published by Programming Line in Android App Development with Kotlin and Jetpack Compose. Last updated .

Module: Data and Offline Workflows · Lecture 22 of 33

Serve useful local data immediately and reconcile remote changes through explicit synchronization policy. This lecture moves from the mental model to implementation, diagnosis, testing, and production tradeoffs.

Prerequisites and Learning Outcomes

Complete the previous lecture and retain its working project. By the end, you should be able to explain the responsibility, implement the example, force a realistic failure, and defend where the behavior belongs in the architecture.

  • Explain the concept without relying on framework buzzwords.
  • Implement it with idiomatic, null-safe Kotlin.
  • Verify success, empty, loading, cancellation, and failure states when applicable.
  • Write a focused automated test and identify one production risk.

Conceptual Model

1. A local database is often the read source of truth for offline-first features.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

2. Queued writes need stable IDs, status, retry policy, and idempotency.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

3. Conflict resolution may be last-write-wins, field merge, server authority, or user choice depending on domain risk.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

Mental-model exercise

Draw the runtime path for this feature as boxes and arrows. Include the user or operating-system event, composable, state owner, ViewModel when appropriate, repository, data source, and final rendered state. Mark which arrows are synchronous, suspending, streamed, or external to the process. Next, mark every place that can fail or be canceled. This diagram should make duplicate ownership, hidden dependencies, and missing recovery paths visible before the implementation becomes large.

Worked Kotlin Example

Type this example into the course project. Read the public contract first, trace one input through every line, and identify what owns any state or resource.

class OfflineTaskRepository(private val dao: TaskDao, private val api: TasksApi) {
  val tasks = dao.observeAll().map { rows -> rows.map(TaskEntity::toDomain) }
  suspend fun refresh() { dao.upsert(api.tasks().map(TaskDto::toEntity)) }
}

Walkthrough

  1. Locate the inputs and their nullability or validity constraints.
  2. Trace the successful path and write down the value and type of each important expression.
  3. Change one assumption: use absent, malformed, delayed, denied, very large, or stale data as appropriate.
  4. Check lifecycle and cancellation behavior by leaving and returning to the screen.
  5. Extract business or data policy from UI code and protect it with a unit test.

Guided Lab

Commit after each verified step. The commit history should tell the story of the feature and make failed experiments recoverable.

Step 1: Render cached data before requesting a refresh.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Step 2: Queue an offline edit and persist its synchronization state.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Step 3: Reconnect, retry safely, and simulate a conflicting remote edit.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Debugging Workshop

Advanced Android work depends on explaining failures across the OS, lifecycle, coroutine, data, and rendering boundaries. Practice with the following cases.

Failure 1

Treating network connectivity as proof a request will succeed.

Reproduce the symptom with fixed input. Reduce it to the smallest component or layer, inspect lifecycle and ownership, correct the underlying contract, and add a regression test. Avoid hiding the failure with a delay, null assertion, broad catch, or UI-only workaround.

Failure 2

Overwriting a newer edit without a documented conflict rule.

Reproduce the symptom with fixed input. Reduce it to the smallest component or layer, inspect lifecycle and ownership, correct the underlying contract, and add a regression test. Avoid hiding the failure with a delay, null assertion, broad catch, or UI-only workaround.

Architecture and Production Decisions

  • Ownership: state and resources need one clear owner and matching cleanup lifetime.
  • Dependency direction: composables render and emit events; ViewModels coordinate screen behavior; repositories own application data; data sources own transport or persistence details.
  • Reliability: distinguish retryable failures from authentication, validation, conflict, and permanent failures.
  • Accessibility: verify semantics, focus, touch target size, font scaling, contrast, and non-visual state feedback.
  • Performance: measure release-like behavior with traces or benchmarks before optimizing.
  • Security: validate external input, minimize stored data, authorize on the server, and keep privileged secrets out of the application.

Independent Assignment

Build: Render cached data before requesting a refresh. Queue an offline edit and persist its synchronization state. Reconnect, retry safely, and simulate a conflicting remote edit.

Add a realistic failure and recovery path that the worked example does not already show. Submit source, analyzer and test output, one screenshot or trace where useful, and a short architecture note explaining ownership and tradeoffs.

Knowledge Check

  1. What problem does this concept solve?
  2. Which layer owns it, and which layer must not own it?
  3. What happens during configuration change, backgrounding, cancellation, or process death?
  4. Which malformed or adversarial input should be tested?
  5. What evidence would demonstrate production readiness?

Answer guide

A complete answer must use these facts: A local database is often the read source of truth for offline-first features. Queued writes need stable IDs, status, retry policy, and idempotency. Conflict resolution may be last-write-wins, field merge, server authority, or user choice depending on domain risk.

It should name an observable behavior, a failure state, and a test boundary. Performance claims need measurement; security claims need a server-side trust boundary; accessibility claims need semantics and device-level verification.

Summary and Official Reference

A local database is often the read source of truth for offline-first features. Queued writes need stable IDs, status, retry policy, and idempotency. Conflict resolution may be last-write-wins, field merge, server authority, or user choice depending on domain risk.

Compare your work with the official Android documentation for this topic. You are ready to continue when you can rebuild the central example, explain its lifecycle and ownership, and show a passing regression test.

Complete Android curriculum · Previous: Preferences DataStore and Typed Settings · Next: WorkManager, Background Limits, and Notifications