Forem: Pulkit Midha

I Built an Offline Kahoot Clone Because Wi-Fi at Conferences Kept Ruining the Fun

Pulkit Midha — Mon, 27 Apr 2026 13:33:12 +0000

If you have ever tried running a live Kahoot quiz with 50+ people in a conference room, you know the pain. Half the audience is fighting for bandwidth, some can not even load the game, and the host is standing there awkwardly while everyone stares at a loading spinner.

I kept running into this problem at developer meetups and workshops. The irony was not lost on me - here we are, all sitting three feet apart, and we need a round trip to some cloud server just to play a quiz together.

So I built KahootP2P. It is a Kahoot-style quiz game for iOS that runs entirely over local peer-to-peer networking. No internet. No router. No cloud. Just devices talking directly to each other, powered by Couchbase Lite Enterprise's P2P replication.

This post walks through why I built it, the architecture decisions I made, and how Couchbase Lite made the hard parts surprisingly simple.

The Problem with Cloud-Dependent Multiplayer

Kahoot is brilliant. The speed-based scoring creates real tension, the simple four-color answer grid works on any screen size, and the leaderboard after each question keeps everyone engaged. But it has a fundamental dependency: every single interaction goes through the internet.

For a classroom with solid Wi-Fi, that is fine. For a packed conference hall where 200 people are sharing a hotel Wi-Fi network? It falls apart fast.

The latency also matters more than you would think. Kahoot awards more points for faster answers. When your correct answer takes 800ms to reach the server instead of 200ms because of network congestion, you are literally losing points through no fault of your own. That is not a great experience.

I wanted something where network latency was measured in single-digit milliseconds, not hundreds. And the only way to get there is to cut out the internet entirely.

Why Couchbase Lite P2P?

When I started thinking about offline multiplayer, my first instinct was Apple's MultipeerConnectivity framework. It handles discovery and basic message passing between iOS devices. But there is a catch - it is designed for mesh topologies where every device talks to every other device. For a quiz game with a host that controls the flow, this creates headaches around consistency and ordering.

What I actually needed was:

A single source of truth - The host device should be the authority on scores, question timing, and game state
Automatic data sync - When the host writes a new question or updates scores, every player should see it without me manually serializing and routing messages
Reliable delivery - If a player's answer takes a moment to sync, it should not get lost

Couchbase Lite Enterprise's peer-to-peer replication fit this perfectly. Here is why:

The URLEndpointListener lets one device (the host) act as a replication target. Player devices connect to it using a standard Couchbase Lite replicator in push-and-pull mode. This gives me a star topology with the host at the center - exactly what a host-authoritative game needs.

The key insight is that I do not have to build a message protocol at all. Instead of thinking about "send question to all players" and "receive answer from player 3," I just write documents to the local database. The replication layer handles getting those documents to the right places.

Architecture: Documents as Game State

The entire game state lives in Couchbase Lite documents. Here is how I modeled it:

Game - A single document that tracks the game title, join code, phase (lobby/asking/closed/finished), and question count. When the host changes the phase, replication pushes it to all players.

class Game: Codable, Identifiable {
    @DocumentID var id: String?
    var title: String
    var joinCode: String
    var phase: GamePhase
    var questionCount: Int
    var createdAt: Date
}

QuestionState - One document that tells every player what question we are on and whether it is still open for answers. The host updates this document to advance the game.

Questions - Individual documents for each question, synced from host to players when the game starts.

Answers - Each player writes their answer as a document. The replication pushes it to the host for scoring.

AnswerResults - After scoring, the host writes result documents back, which replicate to the relevant player.

Leaderboard - A single document with ranked entries, updated by the host after each question.

The beauty of this approach is that the sync is bidirectional and automatic. Players push answers up, the host pushes results down, and Couchbase Lite handles all the conflict resolution and ordering.

Discovery: Finding Games Without a Server

Before devices can replicate data, they need to find each other. I used Bonjour (Apple's zero-configuration networking protocol) for this.

When the host starts a game, two things happen:

A URLEndpointListener starts on an available port
A Bonjour service is published advertising that port

func startHosting(gameId: String) throws {
    var listenerConfig = URLEndpointListenerConfiguration(
        collections: [collection]
    )
    listenerConfig.port = 0  // Let the OS pick a port
    listenerConfig.disableTLS = true

    let urlListener = URLEndpointListener(config: listenerConfig)
    try urlListener.start()

    // Advertise via Bonjour so players can find us
    let service = NetService(
        domain: "",
        type: "_quizblitz._tcp.",
        name: "QuizBlitz-\(gameId.prefix(8))",
        port: Int32(urlListener.port ?? 0)
    )
    service.publish()
}

On the player side, a NetServiceBrowser scans for the _quizblitz._tcp. service type. When it finds a game, the player taps to join, and a Couchbase Lite replicator connects to the host's URLEndpointListener:

func connectToHost(host: String, port: Int) {
    let url = URL(string: "ws://\(host):\(port)/\(db.name)")!
    let targetEndpoint = URLEndpoint(url: url)

    var config = ReplicatorConfiguration(
        collections: [colConfig],
        target: targetEndpoint
    )
    config.replicatorType = .pushAndPull
    config.continuous = true

    let repl = Replicator(config: config)
    repl.start()
}

That is it. Once the replicator is running, documents flow automatically in both directions. No manual message handling.

Scoring: Speed Matters

Like Kahoot, faster correct answers earn more points. But here is the tricky part - in a P2P setup, you can not just use wall-clock timestamps because devices might not have synchronized clocks (and without internet, there is no NTP server to sync with).

My solution uses the host's monotonic clock (via mach_continuous_time) as the single timing reference. When the host opens a question, it records its own uptime in nanoseconds. When an answer document replicates to the host, the host records the receipt time.

let timeDelta = TimingService.elapsedSeconds(
    from: startNs, to: receivedNs
)
let timeBonus = max(0, 1.0 - (timeDelta / Double(timeLimitSeconds)))
let points = isCorrect ? max(100, Int(1000.0 * timeBonus)) : 0

Is this perfectly fair? No. The replication latency adds a few milliseconds of noise. But in practice, over local Wi-Fi, the replication lag is under 50ms. For a game where the time limit is 15 seconds, that noise is negligible. The person who knows the answer and taps faster will still win.

The scoring works on a sliding scale: answer instantly and get 1000 points. Answer at the very last second and get 100 points. Answer wrong and get zero. This creates the same urgency you feel in Kahoot.

Reactive UI with Combine

The UI needs to update in real-time as documents change. Couchbase Lite's Combine integration makes this clean:

db.collectionChangePublisher()
    .receive(on: DispatchQueue.main)
    .sink { [weak self] change in
        self?.handleCollectionChange(change)
    }
    .store(in: &cancellables)

When any document in the collection changes - whether from local writes or incoming replication - this publisher fires. The handler checks if the change is relevant (same game ID) and updates the appropriate state: new player joined, answer received, leaderboard updated.

On the SwiftUI side, the engines are ObservableObject classes with @Published properties. When the host writes a new QuestionState document and it replicates to a player, the player's ClientEngine picks up the change through the collection publisher, updates its @Published properties, and SwiftUI re-renders the view. The whole chain from "host presses Next Question" to "player sees the new question" takes under 100ms on a local network.

The Codable Integration

One of the things that made development faster was Couchbase Lite's Codable support. Instead of manually mapping between documents and Swift objects, I just defined my models as Codable classes:

// Save a model directly
try collection.save(from: game)

// Load it back as a typed object
let game = try collection.document(id: docId, as: Game.self)

The @DocumentID property wrapper automatically maps the Couchbase Lite document ID to a property on the model. This meant I could work with normal Swift objects everywhere and let the SDK handle serialization.

For queries, I used SQL++:

let sql = "SELECT META().id, * FROM _ WHERE gameId = '\(gameId)' 
           AND displayName IS NOT MISSING"
let query = try database.createQuery(sql)

What I Learned

Documents as game state works surprisingly well. I was initially skeptical about using a database replication protocol for real-time game sync. In practice, the latency is low enough that it feels instant, and you get reliable delivery, conflict resolution, and persistence for free.

Star topology is the right call for authoritative games. A mesh network sounds cool, but when one device needs to be the authority on scoring and game flow, a hub-and-spoke model with the host at the center is simpler and more predictable.

You do not need the internet for most local multiplayer. This might seem obvious, but it is easy to default to "spin up a server" when the devices you want to connect are literally in the same room. Couchbase Lite's P2P replication eliminates that entire dependency.

Bonjour discovery just works. I was prepared for a painful debugging session with network discovery, but Bonjour on iOS is rock solid. Devices find each other within 1-2 seconds consistently.

Try It

The full source code is on GitHub: github.com/midopooler/KahootP2P

You will need Couchbase Lite Enterprise (for the URLEndpointListener) and two or more iOS devices on the same local network. Clone the repo, run xcodegen generate, build, and you are playing within a minute.

If you are building any kind of local multiplayer, collaborative, or offline-first experience on mobile, I would strongly recommend looking at Couchbase Lite's P2P capabilities. The fact that I did not have to write a single line of networking code beyond "start the listener" and "start the replicator" saved me a massive amount of time.

The game is simple, but the pattern applies to a lot more than quizzes. Field data collection with team sync. Collaborative note-taking in airplane mode. Point-of-sale systems that keep working when the internet drops. Any time you need multiple devices to share state without depending on the cloud, this same architecture works.

What Happens If Two Android Phones Edit the Same Data Offline?

Pulkit Midha — Thu, 29 Jan 2026 09:41:03 +0000

Short answer: Chaos, unless you planned for it.

Long answer: Let me show you what actually happens when distributed systems meet the real world.

The Scenario

You build an app. Users love it. They install it on multiple devices. Everything works great until one day you get a support ticket:

"I edited my shopping list on my phone, then edited it on my tablet, and now half my items are missing. What happened?"

What happened is that you just learned about conflict resolution the hard way.

The Setup (For Science)

I built a simple test to see exactly what happens. Two Android phones, both running the same app, both offline, both editing the same document at the same time.

// Document before any edits
{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread"],
    "lastModified": 1705320000000
}

Phone A (offline): User adds "butter"
Phone B (offline, same time): User adds "cheese"

Then both phones come online. What happens?

Test 1: Naive Last-Write-Wins (The Disaster)

First, I tried the simplest approach: whoever syncs last wins.

// Pseudo-code for simple sync
fun syncDocument(local: Document, remote: Document): Document {
    return if (local.lastModified > remote.lastModified) {
        local  // Local is newer, push it
    } else {
        remote  // Remote is newer, pull it
    }
}

Phone A syncs first:

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread", "butter"],
    "lastModified": 1705320060000
}

Server now has Phone A's version.

Phone B syncs second:

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread", "cheese"],
    "lastModified": 1705320065000  // 5 seconds later
}

Result: Phone B's version overwrites everything. Phone A's "butter" is gone. User is confused. Developer gets a bad review.

This is bad.

Test 2: Timestamp-Based Merge (The Almost Solution)

Okay, timestamps don't work. What if we track timestamps per field?

// Document with field-level timestamps
{
    "id": "shopping-list-1",
    "title": "Groceries",
    "title_modified": 1705320000000,
    "items": ["milk", "eggs", "bread"],
    "items_modified": 1705320000000
}

Phone A adds "butter":

{
    "items": ["milk", "eggs", "bread", "butter"],
    "items_modified": 1705320060000
}

Phone B adds "cheese":

{
    "items": ["milk", "eggs", "bread", "cheese"],
    "items_modified": 1705320065000
}

Merge logic:

fun mergeFields(local: Document, remote: Document): Document {
    val merged = Document()

    if (local.title_modified > remote.title_modified) {
        merged.title = local.title
    } else {
        merged.title = remote.title
    }

    if (local.items_modified > remote.items_modified) {
        merged.items = local.items
    } else {
        merged.items = remote.items
    }

    return merged
}

Result: Phone B's items win because the timestamp is newer. We still lose "butter".

This is still bad.

Test 3: Operational Transform (The Complex Solution)

What if we track the actual operations?

Phone A: INSERT "butter" at index 3
Phone B: INSERT "cheese" at index 3

Now we can merge the operations:

{
    "items": ["milk", "eggs", "bread", "butter", "cheese"]
}

Perfect! Both changes preserved!

But here's the implementation:

sealed class Operation {
    data class Insert(val index: Int, val value: String) : Operation()
    data class Delete(val index: Int) : Operation()
    data class Update(val index: Int, val value: String) : Operation()
}

fun transformOperations(
    localOps: List<Operation>,
    remoteOps: List<Operation>,
    baseState: List<String>
): List<String> {
    // This is where you spend 3 weeks implementing OT
    // And discover edge cases you never imagined
    // Like: what if one device deletes while another updates?
    // Or: indices shift during concurrent inserts
    // Or: the operations arrive out of order

    // 500 lines of transformation logic later...
}

This works, but good luck maintaining it. Plus, you need to store and sync all operations. And handle out-of-order arrival. And... you get the idea.

Test 4: CRDTs (The Academic Solution)

Conflict-Free Replicated Data Types. Super cool in theory.

// A simple LWW-Element-Set CRDT
class LWWSet<T> {
    private val adds = mutableMapOf<T, Long>()  // Element -> timestamp
    private val removes = mutableMapOf<T, Long>()

    fun add(element: T, timestamp: Long) {
        adds[element] = maxOf(adds[element] ?: 0, timestamp)
    }

    fun remove(element: T, timestamp: Long) {
        removes[element] = maxOf(removes[element] ?: 0, timestamp)
    }

    fun elements(): Set<T> {
        return adds.filter { (element, addTime) ->
            val removeTime = removes[element] ?: 0
            addTime >= removeTime
        }.keys
    }

    fun merge(other: LWWSet<T>) {
        other.adds.forEach { (element, timestamp) ->
            add(element, timestamp)
        }
        other.removes.forEach { (element, timestamp) ->
            remove(element, timestamp)
        }
    }
}

Phone A adds "butter" at time 60:

lwwSet.add("butter", 1705320060000)

Phone B adds "cheese" at time 65:

lwwSet.add("cheese", 1705320065000)

Merge:

lwwSet.merge(otherSet)
// Result: ["milk", "eggs", "bread", "butter", "cheese"]

This works! Both edits preserved!

But now your data structure is completely different. And you need to implement CRDTs for every data type. And explain to your team what a CRDT is. And...

There has to be a better way.

Test 5: Couchbase Lite (The Practical Solution)

Couchbase uses a revision tree. Every change creates a new revision. Conflicts are detected automatically.

Let me show you what actually happens:

Initial document (revision 1-abc):

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread"],
    "_rev": "1-abc"
}

Phone A (offline) adds "butter" -> creates revision 2-def:

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread", "butter"],
    "_rev": "2-def",
    "_revisions": {
        "start": 2,
        "ids": ["def", "abc"]
    }
}

Phone B (offline) adds "cheese" -> creates revision 2-ghi:

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread", "cheese"],
    "_rev": "2-ghi",
    "_revisions": {
        "start": 2,
        "ids": ["ghi", "abc"]
    }
}

Both revisions branched from 1-abc. This is a conflict.

When sync happens:

Couchbase detects the conflict because two revisions have the same parent. It marks one as the "winner" (deterministically based on revision ID), but keeps both.

// Phone A's view after sync
{
    "id": "shopping-list-1",
    "_rev": "2-ghi",  // Winner (alphabetically later)
    "items": ["milk", "eggs", "bread", "cheese"],
    "_conflicts": ["2-def"]  // Loser is preserved
}

Now here's the cool part: I can write a custom conflict resolver.

val config = ReplicatorConfigurationFactory.create(
    database = database,
    target = endpoint,
    conflictResolver = { conflict ->
        val local = conflict.localDocument
        val remote = conflict.remoteDocument

        // Both documents exist, merge the items
        val localItems = local.getArray("items")?.toList() ?: emptyList()
        val remoteItems = remote.getArray("items")?.toList() ?: emptyList()

        // Merge: take all unique items from both
        val mergedItems = (localItems + remoteItems).distinct()

        val merged = MutableDocument(local.id)
        merged.setString("title", local.getString("title"))
        merged.setArray("items", MutableArray(mergedItems))
        merged.setLong("lastModified", System.currentTimeMillis())

        merged
    }
)

Result after conflict resolution:

{
    "id": "shopping-list-1",
    "title": "Groceries",
    "items": ["milk", "eggs", "bread", "butter", "cheese"],
    "_rev": "3-xyz"
}

Both edits preserved. No data loss. Automatic sync. Beautiful.

The Real-World Test

I actually tested this with two physical devices:

Test A: Concurrent Adds

Phone 1 (offline): Add "tomatoes"
Phone 2 (offline): Add "onions"
Both come online
Result: Both items appear
✅ Success

Test B: Concurrent Updates to Same Item

Both phones have item: "apples (2)"
Phone 1 (offline): Change to "apples (3)"
Phone 2 (offline): Change to "apples (5)"
Both come online
Result: My resolver kept the higher quantity
✅ Success (with custom logic)

Test C: Delete vs Update

Phone 1 (offline): Delete item "bananas"
Phone 2 (offline): Update "bananas" to "bananas (ripe)"
Both come online
Result: My resolver keeps the update (prefer data retention)
✅ Success (with custom logic)

Test D: Complete List Reorder

Phone 1 (offline): Reorder list A-Z
Phone 2 (offline): Reorder list by category
Both come online
Result: Last sync wins (can't merge reorders intelligently)
⚠️ Acceptable loss

What About Room?

Could you build this with Room? Technically yes. Would you want to? No.

You'd need:

Manual revision tracking
Conflict detection logic
Merge algorithms
Sync coordination
Server-side conflict resolution
At least 1000 lines of code

Or you could use Couchbase and write 50 lines.

The Code

Here's my complete conflict resolver for the shopping list:

private fun resolveShoppingListConflict(conflict: Conflict): Document {
    val local = conflict.localDocument ?: return conflict.remoteDocument!!
    val remote = conflict.remoteDocument ?: return local

    // Get items from both versions
    val localItems = mutableSetOf<String>()
    local.getArray("items")?.forEach { item ->
        (item as? String)?.let { localItems.add(it) }
    }

    val remoteItems = mutableSetOf<String>()
    remote.getArray("items")?.forEach { item ->
        (item as? String)?.let { remoteItems.add(it) }
    }

    // Merge: union of both sets
    val mergedItems = localItems + remoteItems

    // Create merged document
    val merged = MutableDocument(local.id)
    merged.setString("title", local.getString("title") ?: remote.getString("title") ?: "")
    merged.setArray("items", MutableArray(mergedItems.toList()))
    merged.setLong("lastModified", System.currentTimeMillis())
    merged.setString("type", "shopping-list")

    return merged
}

That's it. 25 lines. Handles all concurrent edits.

Performance Impact

I measured sync times with conflicts:

No conflict:

Sync time: ~100ms
Network: 1 request

With conflict (default resolver):

Sync time: ~120ms
Network: 2 requests (detect + resolve)

With conflict (custom resolver):

Sync time: ~150ms
Network: 2 requests

The overhead is minimal. Users won't notice.

Edge Cases I Discovered

Same Edit on Both Devices

If both phones add "butter" while offline, the default resolver recognizes they're identical and doesn't create a conflict. Smart.

Very Old Offline Edit

Phone A goes offline for a week. Makes edits. Comes back online. Phone B has made 50 changes in that time.

Couchbase's revision tree handles this. It merges based on the branching point, not the absolute time. Works perfectly.

Three-Way Conflicts

Phone A, Phone B, and Phone C all edit while offline. All sync at once.

Couchbase resolves them pairwise. My resolver runs multiple times. Final result includes all changes. Magic.

When It Doesn't Work

Not all conflicts can be auto-resolved:

Semantic Conflicts

Phone A: Set meeting time to 2 PM
Phone B: Set meeting time to 4 PM

Which is correct? The resolver doesn't know. You need user intervention.

My solution: surface conflicts to the user when they're ambiguous.

private fun requiresUserIntervention(conflict: Conflict): Boolean {
    val local = conflict.localDocument ?: return false
    val remote = conflict.remoteDocument ?: return false

    // Same field changed to different values?
    val criticalFields = listOf("meetingTime", "price", "quantity")

    return criticalFields.any { field ->
        local.getValue(field) != remote.getValue(field) &&
        local.getValue(field) != null &&
        remote.getValue(field) != null
    }
}

Complex Business Logic

"If status is 'approved', don't allow edits" type rules.

The database doesn't know your business logic. You need to enforce it in the app.

Lessons Learned

Timestamps lie: Clocks aren't synchronized. Never trust timestamps alone.
Last-write-wins loses data: Unless that's explicitly what you want.
Automatic merge is hard: But letting a battle-tested library do it is easy.
Most conflicts are mergeable: 90% of my conflicts merge automatically.
The other 10% need UI: Show users the conflict, let them decide.

Best Practices

1. Design for Conflicts

Assume conflicts will happen. They will.

2. Merge When Possible

Union sets, combine arrays, prefer data retention over deletion.

3. Let Users Decide When Unsure

Don't silently discard data.

4. Test With Real Devices

Emulators don't capture the real experience of offline editing.

5. Log Everything

When conflicts happen, log them. You'll learn patterns.

The Bottom Line

Two phones editing the same data offline is not a hypothetical. It's a real scenario that happens all the time:

User edits doc on phone during commute (no signal)
User edits same doc on laptop at office
Both sync when user arrives

If you're building multi-device apps, you need a conflict resolution strategy. You have three options:

Manual implementation: Hard, buggy, time-consuming
Academic solutions (OT/CRDTs): Powerful, complex, overkill for most apps
Use Couchbase Lite: Practical, battle-tested, actually works

I chose option 3. My conflicts resolve automatically. My users don't lose data. I sleep well at night.

Have you dealt with offline conflicts in your apps? What strategies did you use? I'd love to hear about your experiences in the comments.

I Tried to Build Multi-Device Sync with Room (So You Don't Have To)

Pulkit Midha — Thu, 29 Jan 2026 09:37:55 +0000

Look, I get it. Room is great. It's clean, it's type-safe, and it fits perfectly into the Android ecosystem. I've built probably a dozen apps with it, and I've never had complaints. Until last month.

My PM walks up and says, "Hey, can we sync this data across devices?" Sure, I thought. How hard could it be?

Spoiler: Very hard.

The Plan (That Seemed Reasonable at 9 AM)

I had a simple notes app using Room. The schema was straightforward:

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey val id: String = UUID.randomUUID().toString(),
    val title: String,
    val content: String,
    val lastModified: Long = System.currentTimeMillis()
)

My brilliant plan:

Set up a REST API on the backend
Send local changes to the server
Pull remote changes and merge them
Profit?

Reality Check 1: The Manual API Hell

First problem: Room doesn't have any built-in sync. Everything is manual. So I had to:

Track which notes were dirty (modified locally)
Queue them for upload
Handle network failures
Retry failed uploads
Deal with partial syncs
Track sync state per note

I ended up adding fields to my entity:

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey val id: String = UUID.randomUUID().toString(),
    val title: String,
    val content: String,
    val lastModified: Long = System.currentTimeMillis(),
    val syncStatus: SyncStatus = SyncStatus.PENDING,
    val lastSyncedAt: Long? = null,
    val isDirty: Boolean = false
)

Great. Now my clean entity is cluttered with sync metadata.

Reality Check 2: Conflict Hell

Here's where things got fun. User edits "Meeting Notes" on their phone, then edits the same note on their tablet before the phone syncs. Which version wins?

My first attempt: "Last write wins based on timestamp."

Sounds reasonable, right? Except:

Clocks aren't always in sync
Network delays mean "last" is relative
Users get really mad when their edits disappear

I tried version vectors. I tried vector clocks. I tried telling myself this was a learning experience.

// My attempt at conflict resolution
fun resolveConflict(local: Note, remote: Note): Note {
    return when {
        local.lastModified > remote.lastModified -> local
        local.lastModified < remote.lastModified -> remote
        else -> {
            // Same timestamp? Now what?
            // Merge content? Prompt user? Flip a coin?
            Log.e("Sync", "Help")
            remote // I gave up
        }
    }
}

Reality Check 3: The Duplicate Row Problem

You know what's worse than losing data? Having two copies of the same note because the UUID generated on the phone doesn't match the ID the server assigned.

I had to implement ID mapping:

data class IdMapping(
    val localId: String,
    val remoteId: String
)

And a whole separate table to track it. My "simple" sync was now three tables deep.

Reality Check 4: Race Conditions Everywhere

User opens app while sync is running -> stale data
User edits note during sync -> which version do we keep?
Sync starts while user is editing -> UI flickers
Multiple devices sync at once -> chaos

I added locks. I added queues. I added way too many synchronized blocks. My code was starting to look like a threading textbook gone wrong.

private val syncLock = ReentrantReadWriteLock()

suspend fun syncNotes() {
    syncLock.writeLock().lock()
    try {
        // 50 lines of sync logic
        // 30 lines of error handling
        // 10 lines of "TODO: fix this properly"
    } finally {
        syncLock.writeLock().unlock()
    }
}

Breaking Point

After two weeks of this, I had:

800+ lines of sync code
15 different edge cases in my test suite
A bug where notes would randomly duplicate
Another bug where deletions wouldn't sync
A third bug that only happened on Tuesdays (I'm not joking)

I started Googling alternatives.

Enter Couchbase Lite

I'm not going to lie, I was skeptical. "Just use another database" felt like giving up. But I was desperate.

The setup:

// That's it. That's the entire initial setup.
val database = Database("myapp")

Adding sync:

val replicator = Replicator(
    ReplicatorConfigurationFactory.create(
        database = database,
        target = URLEndpoint(URI("ws://localhost:4984/mydb")),
        type = ReplicatorType.PUSH_AND_PULL,
        continuous = true
    )
)
replicator.start()

That's it. No sync status tracking. No conflict resolution hell. No duplicate IDs. It just... works.

How It Actually Handles Conflicts

Remember my terrible conflict resolution code? Couchbase does this automatically:

// Define custom conflict resolver if you need it
val config = ReplicatorConfigurationFactory.create(
    database = database,
    target = target,
    conflictResolver = { conflict ->
        val local = conflict.localDocument
        val remote = conflict.remoteDocument
        // Actually merge the content intelligently
        // Or just pick one
        local // Your choice, but it won't lose data randomly
    }
)

But honestly? The default resolver is pretty smart. It maintains revision history and merges changes. I haven't had to write a custom resolver yet.

What About the Learning Curve?

Not gonna lie, there's some new concepts:

Documents instead of entities
Revision IDs
The whole CouchDB replication protocol

But compared to implementing sync from scratch? This is a weekend, not a month.

The Numbers

Room + Manual Sync:

800+ lines of sync code
2 weeks of development
Still had bugs
Nervous about scaling

Couchbase Lite:

~50 lines for full sync setup
1 day to integrate
Zero sync bugs so far
Built-in conflict resolution

Should You Switch?

Look, if you're building a single-device app that never needs to sync, stick with Room. It's lighter and simpler.

But if you're even thinking about:

Multi-device sync
Offline-first architecture
Real-time collaboration
Data conflicts between devices

Save yourself the pain. Use Couchbase Lite from the start.

The Catch

There's always a catch:

Slightly larger APK size
Need to run Sync Gateway for server sync
Different query syntax (though it's SQL-like)

For me? Totally worth it. My sync code went from "oh god why" to "oh, it just works."

Final Thoughts

I spent two weeks trying to reinvent the wheel with Room. Turns out, other people have already solved this problem, and they did a better job than I ever would.

Sometimes the right tool isn't the one you're already comfortable with. Sometimes it's the one that actually solves your problem.

Now if you'll excuse me, I have 800 lines of sync code to delete.

Have you tried implementing sync with Room? Did you succeed where I failed? Or did you also end up Googling "why is distributed systems so hard" at 2 AM? Let me know in the comments.