/Projects

Offline outbox with idempotent sync

Writes persist first, sync later, survive kills, and are never applied twice.

PracticeMachine codingTier 3 · Edge casesCreate45 minMobile systems

You will be able to: build offline outbox with idempotent sync in 45 minutes, edge cases included.

Source: Tested in tests/mobile/MobileTests.kt

Mobile engineeringReact Native in one place17 of 22Next: Resumable multipart uploader →

Op 7f3a waits in this structure from 2:40 to 4:12 pm. You build the queue that makes a retry safe and lets the process die at any line. Start from the basics in Day 2 →

Study with AI

45-minute round · HardKotlin · coroutines · tested Watch as reels
Part 1 of 5

Basics

The concepts this component is built on. With these in mind, every line of the solution has a reason.

1.1Key concepts

One idea per card, in the order the solution uses them.

01Offline-first writes

The app saves a change locally and returns at once. Sending it to the server happens later, in the background.

02Outbox queue

A durable, ordered list of changes waiting to be sent. It survives app kills because it lives in the database, not in memory.

03Idempotency key

A unique id per change. The server remembers the ids it has applied, so a retried send is answered with 'duplicate' instead of being applied twice.

04Retryable vs permanent errors

Timeouts and 5xx responses may succeed later; validation errors never will. Retrying the second kind only blocks the queue.

Part 2 of 5

Question

What exactly you are asked to build, what must be true when you are done, and what to ask before you start.

2.1Prompt

The question as the interviewer asks it, and the requirements to check your solution against.

Interviewer

Field technicians edit jobs with no signal. Implement the client side of the outbox: changes must never be lost, must reach the server in order, and must not be applied twice when we retry.

Requirements

  • Enqueue persists before returning
  • Drain in order; stop when offline
  • Retry with backoff, honouring server hints
  • Park permanently failing ops for the user
  • Only one drain at a time

2.2Clarify first

Questions worth asking, and the answers this interviewer gives.

You askInterviewer answers
Does the server support idempotency keys?Yes: it stores processed op ids and returns 'duplicate' for repeats.
What if one op is permanently invalid?Park it so the queue keeps moving, and show it to the user.
Who triggers drain?A unique WorkManager job, app start and connectivity changes.
Part 3 of 5

Detailed answer

The design decisions, the complete Kotlin solution, and a walk through it one block at a time.

3.1Design decisions

Settle these before writing code; each one shows up in the solution.

Op id = idempotency key

Generated on the device before the first send, so a retry after a lost response is harmless.

Persist on every transition

Enqueue, success and retry all save, so a kill at any line loses nothing.

Typed results

A sealed interface of Applied, Duplicate, Retryable and Rejected makes the policy explicit, and when is checked to be exhaustive.

Two locks, two jobs

One Mutex guards the queue; a second, taken with tryLock, keeps drain single-flight. The network call holds neither.

3.2Solution

Complete, compiling Kotlin with coroutines, built with warnings as errors and covered by tests/mobile/MobileTests.kt. The Java and TypeScript tabs do the same job with each language's own tools: Java compiled and run in our tests, TypeScript run in our tests.

Outbox.ktKotlin
1import java.io.IOException2import java.util.UUID3import kotlin.time.Duration4import kotlinx.coroutines.sync.Mutex5import kotlinx.coroutines.sync.withLock6 7/**8 * One pending local change. [id] is generated on the device and doubles as the9 * idempotency key, so a retried push is applied by the server at most once.10 */11data class PendingOp(12  val entity: String,13  val payload: String,14  val id: String = UUID.randomUUID().toString(),15  val attempts: Int = 0,16)17 18sealed interface PushResult {19  data object Applied : PushResult20  data object Duplicate : PushResult                   // server already applied this id: success21  data class Retryable(val after: Duration?) : PushResult   // 429 / 5xx22  data class Rejected(val reason: String) : PushResult      // 4xx validation: never retry23}24 25fun interface SyncTransport {26  suspend fun push(op: PendingOp): PushResult          // throws IOException when offline27}28 29interface OutboxStore {30  suspend fun load(): List<PendingOp>31  suspend fun save(ops: List<PendingOp>)32}33 34/**35 * Durable, ordered queue of local writes. The UI enqueues and moves on; a sync job36 * drains it whenever the OS gives us time. Safe to kill at any line.37 */38class Outbox(39  private val store: OutboxStore,40  private val transport: SyncTransport,41  private val maxAttempts: Int = 8,42) {43  sealed interface DrainOutcome {44    data object Drained : DrainOutcome45    data object Offline : DrainOutcome46    data class Backoff(val delay: Duration) : DrainOutcome47    data object AlreadyRunning : DrainOutcome48  }49 50  private val state = Mutex()                          // guards queue, parked and loaded51  private val draining = Mutex()                       // single flight52  private val queue = ArrayDeque<PendingOp>()53  private val parked = mutableListOf<PendingOp>()      // needs the user's attention54  private var loaded = false55 56  suspend fun pendingCount(): Int = state.withLock { loadIfNeeded(); queue.size }57  suspend fun parkedOps(): List<PendingOp> = state.withLock { parked.toList() }58 59  /** Persist first, then return: if the app dies a millisecond later, the intent survives. */60  suspend fun enqueue(op: PendingOp) = state.withLock {61    loadIfNeeded()62    queue.addLast(op)63    store.save(queue.toList())64  }65 66  suspend fun drain(): DrainOutcome {67    if (!draining.tryLock()) return DrainOutcome.AlreadyRunning   // a drain is already running68    try {69      while (true) {70        val op = state.withLock { loadIfNeeded(); queue.firstOrNull() } ?: return DrainOutcome.Drained71        val result = try {72          transport.push(op)73        } catch (e: IOException) {74          return DrainOutcome.Offline                  // keep everything; try again later75        }76        state.withLock {77          when (result) {78            PushResult.Applied, PushResult.Duplicate -> queue.removeFirst()79            is PushResult.Rejected -> parked += queue.removeFirst()80            is PushResult.Retryable -> {81              val next = op.copy(attempts = op.attempts + 1)82              queue.removeFirst()83              if (next.attempts >= maxAttempts) {84                parked += next85              } else {86                queue.addFirst(next)87                store.save(queue.toList())88                return DrainOutcome.Backoff(result.after ?: Backoff.delay(next.attempts))89              }90            }91          }92          store.save(queue.toList())                   // checkpoint after every op93        }94      }95    } finally {96      draining.unlock()97    }98  }99 100  private suspend fun loadIfNeeded() {101    if (loaded) return102    val saved = store.load()103    queue.addAll(0, saved)104    loaded = true105  }106}
106 linesUTF-8Kotlin

3.3Line-by-line walkthrough

The same code in the order you would explain it in the room. The line numbers follow the Kotlin file; the Java and TypeScript tabs above have the same steps in the same order.

1

The op carries its own key

A UUID created on the device. The server dedupes by it, so retries are safe.

Outbox.ktKotlin
11data class PendingOp(12  val entity: String,13  val payload: String,14  val id: String = UUID.randomUUID().toString(),15  val attempts: Int = 0,16)
lines 11–16UTF-8Kotlin
2

Every server answer has a policy

Duplicate counts as success; 429/5xx is retryable; 4xx validation is rejected for good.

Outbox.ktKotlin
18sealed interface PushResult {19  data object Applied : PushResult20  data object Duplicate : PushResult                   // server already applied this id: success21  data class Retryable(val after: Duration?) : PushResult   // 429 / 5xx22  data class Rejected(val reason: String) : PushResult      // 4xx validation: never retry23}
lines 18–23UTF-8Kotlin
3

Persist before returning

The UI gets control back only after the intent is on disk.

Outbox.ktKotlin
60  suspend fun enqueue(op: PendingOp) = state.withLock {61    loadIfNeeded()62    queue.addLast(op)63    store.save(queue.toList())64  }
lines 60–64UTF-8Kotlin
4

Single flight

tryLock fails if a drain is already running, so a second trigger returns at once instead of sending twice.

Outbox.ktKotlin
67    if (!draining.tryLock()) return DrainOutcome.AlreadyRunning   // a drain is already running68    try {
lines 67–68UTF-8Kotlin
5

Push in order; offline stops

Peek under the lock, push without it. An IOException means no network: keep everything and wait for the next trigger.

Outbox.ktKotlin
70        val op = state.withLock { loadIfNeeded(); queue.firstOrNull() } ?: return DrainOutcome.Drained71        val result = try {72          transport.push(op)73        } catch (e: IOException) {74          return DrainOutcome.Offline                  // keep everything; try again later75        }
lines 70–75UTF-8Kotlin
6

Success or permanent failure

Remove applied and duplicate ops; park rejected ones so the queue keeps moving.

Outbox.ktKotlin
77          when (result) {78            PushResult.Applied, PushResult.Duplicate -> queue.removeFirst()79            is PushResult.Rejected -> parked += queue.removeFirst()
lines 77–79UTF-8Kotlin
7

Retry with backoff

Count the attempt, persist it, and return the server's Retry-After or a jittered backoff. Too many attempts → park.

Outbox.ktKotlin
80            is PushResult.Retryable -> {81              val next = op.copy(attempts = op.attempts + 1)82              queue.removeFirst()83              if (next.attempts >= maxAttempts) {84                parked += next85              } else {86                queue.addFirst(next)87                store.save(queue.toList())88                return DrainOutcome.Backoff(result.after ?: Backoff.delay(next.attempts))89              }90            }
lines 80–90UTF-8Kotlin
8

Checkpoint after each op

A kill now replays at most one op, and the server ignores the duplicate.

Outbox.ktKotlin
92          store.save(queue.toList())                   // checkpoint after every op
lines 92–92UTF-8Kotlin

Complexity: O(1) per op plus one store write; the queue is FIFO

Part 4 of 5

Q&A

The questions interviewers ask after the code works. Answer out loud, then open.

4.1Follow-up questions

How would you batch?
Send up to N ops per request; the server returns a result per op id and the client applies the same policy to each.
What about ordering across entities?
One queue keeps global order. If entities are independent you can run one queue per entity type for parallelism.
How does the UI show pending state?
Each local row has a sync-status column updated in the same Room transaction as the outbox.
Part 5 of 5

Extra depth

The cases that break naive solutions, how the same design looks on iOS, and what to practise next.

5.1Edge cases

Say these before the interviewer does.

Show detailsHide details
  • Killed between the server applying an op and us saving: the retry returns 'duplicate'
  • An op that fails validation forever
  • Two triggers arrive at once
  • The queue grows large offline: batch pushes and compact edits to the same record

5.2On iOS

The same design in Swift and Apple's frameworks.

Show detailsHide details
ApproachSwift / iOS
StorageA GRDB or SwiftData table, written in the same transaction as the entity change.
SchedulingBGProcessingTask with requiresNetworkConnectivity, plus a drain on launch and on NWPathMonitor changes.
ConcurrencyAn actor with a draining flag; actors are re-entrant at await, so the flag is still needed.
AI Engineer · Offline outbox with idempotent sync