What we're building

By the end of this tutorial, you'll have a working mental model — and working code — for implementing Conflict-Free Replicated Data Types in Kotlin Multiplatform shared code. We'll build an LWW-Register, compare state-based vs operation-based sync strategies, and walk through the architecture that lets you replace your entire sync backend with dumb blob storage.

Let me show you a pattern I use in every project with offline-first requirements.

Prerequisites

• Kotlin Multiplatform project set up with commonMain, Android, and iOS targets
• Familiarity with Kotlin data classes and basic merge logic
• SQLDelight (recommended for local persistence)

Step 1: Understand why custom sync servers fail

Most teams build a centralized arbiter — a server that receives conflicting writes, applies "last write wins" at the field level, and hopes for the best. This creates a single point of failure and an ever-growing surface area of edge-case conflict logic nobody wants to maintain.

CRDTs flip the model. Every replica converges to the same state given the same set of updates. Mathematically guaranteed, no coordination required.

Step 2: Pick the right primitives

Not every CRDT is practical on constrained devices. Here is the minimal setup to get this working:

For most mobile apps, LWW-Registers and OR-Sets cover the majority of sync needs. RGA is only necessary when you need ordered, collaborative sequences.

Step 3: Implement an LWW-Register in commonMain

One implementation, every platform. Drop this into your shared module:

data class LWWRegister<T>(
    val value: T,
    val timestamp: Long,
    val nodeId: String
) {
    fun merge(other: LWWRegister<T>): LWWRegister<T> = when {
        other.timestamp > this.timestamp -> other
        other.timestamp < this.timestamp -> this
        else -> if (other.nodeId > this.nodeId) other else this
    }
}

The nodeId tiebreaker matters more than people realize. Without it, identical timestamps produce non-deterministic merges, which violates the convergence guarantee. The docs do not mention this, but most tutorials skip this detail entirely.

Step 4: Choose state-based vs operation-based

On mobile, state-based CRDTs are the pragmatic default. 3G connections drop mid-sync. Apps get backgrounded and sockets die. Requiring exactly-once delivery for operation-based CRDTs means building a reliable causal broadcast layer — which reintroduces the backend complexity you were trying to escape.

If your documents grow large, delta-state CRDTs offer a hybrid approach: transmit only the state diff since last sync, reclaiming bandwidth without sacrificing idempotency.

Step 5: Handle vector clocks without fear

Vector clocks track causal ordering across replicas. Here is the gotcha that will save you hours: on mobile, the constraint is friendlier than it sounds. Most users have a bounded number of devices. A vector clock with entries for a phone, tablet, and laptop is three integers. That's nothing.

Prune entries for devices inactive beyond a threshold, and the metadata stays compact. Store vector clocks alongside each CRDT in SQLDelight, and compare them during sync to detect concurrent updates versus causal successors.

For Automerge integration, wrap the native Rust-based library via expect/actual declarations — JNI on Android, C interop on iOS through the shared boundary.

Step 6: Delete your sync service

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Android  │     │   iOS    │     │ Desktop  │
└────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │
     │   CRDT State Blobs (opaque)     │
     └────────┬───────┴───────┬────────┘
              ▼               ▼
        ┌───────────────────────┐
        │   Dumb Storage Relay  │
        │  (S3 / Cloud Storage) │
        │  No conflict logic    │
        └───────────────────────┘

Your "backend" becomes a storage relay. It holds opaque CRDT state blobs, knows nothing about your data model, resolves zero conflicts, and scales with commodity object storage pricing. You delete the sync service, its tests, its deployment pipeline, and its on-call rotation.

Gotchas

• Missing nodeId tiebreaker: Without deterministic tiebreaking on equal timestamps, your LWW-Register violates convergence. Always include it.
• Reaching for operation-based CRDTs too early: They require exactly-once delivery guarantees. On mobile networks, that means building infrastructure you were trying to avoid.
• Optimizing payload size before measuring: State-based payloads for typical mobile data sets (preferences, local lists, document fragments) stay well within acceptable bounds. Reach for delta-state variants only when payload sizes become a measured problem, not a theoretical one.
• Overestimating vector clock overhead: You're not running thousands of nodes. You're tracking three devices.

Conclusion

Start with LWW-Registers and OR-Sets in commonMain. These two primitives cover user settings, favorites, tags, and most entity-level sync needs. Write platform-agnostic property tests that verify convergence. Default to state-based CRDTs — the idempotent merge model tolerates unreliable networks without additional infrastructure.

Once your clients can independently merge state, your backend doesn't need conflict resolution logic anymore. Reduce it to authenticated blob storage and spend that engineering time on product work instead.