Building Resilient Offline-First Apps with Rork Max — Local-First Databases, Sync Engines & Conflict Resolution

// Local storage abstraction
protocol LocalDataStore {
    func saveChanges(_ changes: [EntityChange]) async throws
    func fetchEntity<T: Identifiable>(_ id: T.ID) -> T?
    func queryEntities<T>(matching predicate: NSPredicate) -> [T]
}
 
// Change tracking
struct EntityChange: Codable {
    let entityId: String
    let entityType: String
    let operation: Operation // .create, .update, .delete
    let timestamp: Date
    let data: AnyCodable
    let clientId: String // Identifies which client made the change
}
 
// Sync engine state
actor SyncEngine {
    private let localStore: LocalDataStore
    private let networkService: NetworkService
    private var pendingChanges: [EntityChange] = []
    private var lastSyncTimestamp: Date?
 
    func recordChange(_ change: EntityChange) async throws {
        pendingChanges.append(change)
        try await localStore.saveChanges([change])
        await triggerSyncIfNeeded()
    }
 
    func sync() async throws {
        guard !pendingChanges.isEmpty else { return }
 
        // Batch pending changes
        let batch = pendingChanges
 
        // Send to server
        let response = try await networkService.syncChanges(batch)
 
        // Apply server changes and resolve conflicts
        let resolved = try resolveConflicts(batch, with: response.serverChanges)
 
        // Update local store with resolved state
        try await localStore.saveChanges(resolved)
 
        // Clear pending changes
        pendingChanges.removeAll()
        lastSyncTimestamp = Date()
    }
}

// WCDB setup for offline-first apps
import WCDB
 
class WCDBOfflineStore: LocalDataStore {
    let db: Database
 
    init(path: String) throws {
        db = try Database(at: path)
        try setupSchema()
    }
 
    private func setupSchema() throws {
        // Changes table for sync tracking
        try db.create(table: "entity_changes", of: EntityChange.self)
        try db.create(index: "idx_pending_sync",
                     on: "entity_changes",
                     indexesBy: ["timestamp", "isSynced"])
 
        // Version vectors for causality tracking
        try db.create(table: "version_vectors", of: VersionVector.self)
        try db.create(index: "idx_entity_version",
                     on: "version_vectors",
                     indexesBy: ["entityId"])
    }
 
    func saveChanges(_ changes: [EntityChange]) async throws {
        try db.inTransaction {
            for change in changes {
                try db.insert(change, intoTable: "entity_changes")
                try updateVersionVector(for: change)
            }
        }
    }
 
    private func updateVersionVector(for change: EntityChange) throws {
        let vector = try db.selectOne(
            on: VersionVector.self,
            from: "version_vectors",
            where: "entityId" == change.entityId
        ) ?? VersionVector(entityId: change.entityId, clock: [:])
 
        var updatedVector = vector
        updatedVector.clock[change.clientId, default: 0] += 1
 
        try db.update(table: "version_vectors",
                      on: VersionVector.self,
                      with: updatedVector,
                      where: "entityId" == change.entityId)
    }
}

import RealmSwift
 
class Task: Object, ObjectKeyIdentifiable {
    @Persisted(primaryKey: true) var id: ObjectId
    @Persisted var title: String = ""
    @Persisted var description: String = ""
    @Persisted var status: String = "pending"
    @Persisted var assignedUsers: MutableSet<User>
    @Persisted var lastModified: Date = Date()
    @Persisted var clientId: String = ""
    @Persisted var syncedAt: Date?
    @Persisted var isSynced: Bool = false
}
 
class RealmOfflineStore: LocalDataStore {
    let realm: Realm
 
    init() throws {
        // Configure Realm for offline-first
        var config = Realm.Configuration.defaultConfiguration
        config.schemaVersion = 1
 
        // Add migration for schema updates without data loss
        config.migrationBlock = { migration, oldVersion in
            if oldVersion < 1 {
                // Add new columns for offline tracking
                migration.renameProperty(onType: "Task", from: "modified", to: "lastModified")
            }
        }
 
        Realm.Configuration.defaultConfiguration = config
        realm = try Realm()
    }
 
    func saveChanges(_ changes: [EntityChange]) async throws {
        try await realm.asyncWrite {
            for change in changes {
                switch change.operation {
                case .create, .update:
                    let task = Task()
                    task.id = ObjectId(timestamp: UInt32(Date().timeIntervalSince1970),
                                      machineIdentifier: [0, 0, 0],
                                      processIdentifier: UInt16.random(in: 0..<65536),
                                      counter: UInt32.random(in: 0..<16777215))
                    task.title = change.data["title"] as? String ?? ""
                    task.lastModified = change.timestamp
                    task.isSynced = false
                    self.realm.add(task, update: .modified)
 
                case .delete:
                    let predicate = NSPredicate(format: "id == %@", change.entityId as CVarArg)
                    let toDelete = self.realm.objects(Task.self).where(predicate)
                    self.realm.delete(toDelete)
                }
            }
        }
    }
 
    func getPendingChanges() throws -> [EntityChange] {
        let unsyncedTasks = realm.objects(Task.self).where { !$0.isSynced }
        return unsyncedTasks.map { task in
            EntityChange(
                entityId: task.id.stringValue,
                entityType: "Task",
                operation: .update,
                timestamp: task.lastModified,
                data: AnyCodable(["title": task.title]),
                clientId: task.clientId
            )
        }
    }
}

struct LastWriteWinsElement<Value: Codable>: Codable {
    let value: Value
    let timestamp: UInt64 // Logical clock or physical time
    let clientId: String
 
    // For comparison in conflict resolution
    func isNewerThan(_ other: LastWriteWinsElement<Value>) -> Bool {
        if timestamp != other.timestamp {
            return timestamp > other.timestamp
        }
        return clientId > other.clientId // Tie-breaker: lexicographic order
    }
}
 
class LWWCRDTSyncEngine {
    func merge<Value: Codable>(
        local: LastWriteWinsElement<Value>,
        remote: LastWriteWinsElement<Value>
    ) -> LastWriteWinsElement<Value> {
        // Always keep the version with the higher timestamp
        remote.isNewerThan(local) ? remote : local
    }
 
    func mergeConflictingChanges(
        localChanges: [EntityChange],
        remoteChanges: [EntityChange]
    ) -> [EntityChange] {
        var merged: [String: EntityChange] = [:]
 
        // Process both sets of changes
        for change in localChanges + remoteChanges {
            let key = change.entityId
 
            if let existing = merged[key] {
                // Keep the change with higher timestamp
                let existingTime = UInt64(existing.timestamp.timeIntervalSince1970 * 1000)
                let newTime = UInt64(change.timestamp.timeIntervalSince1970 * 1000)
 
                if newTime > existingTime ||
                   (newTime == existingTime && change.clientId > existing.clientId) {
                    merged[key] = change
                }
            } else {
                merged[key] = change
            }
        }
 
        return Array(merged.values)
    }
}

struct VectorClockElement: Codable, Equatable {
    let value: String
    let vectorClock: [String: UInt64] // clientId -> logical clock
    let clientId: String
 
    func happensBefore(_ other: VectorClockElement) -> Bool {
        var atLeastOneLess = false
 
        for (clientId, time) in vectorClock {
            let otherTime = other.vectorClock[clientId] ?? 0
            if time > otherTime {
                return false // This happened after, not before
            }
            if time < otherTime {
                atLeastOneLess = true
            }
        }
 
        return atLeastOneLess
    }
 
    mutating func increment(by clientId: String) {
        vectorClock[clientId, default: 0] += 1
    }
}
 
class VectorClockSyncEngine {
    func detectConcurrentChanges(
        change1: VectorClockElement,
        change2: VectorClockElement
    ) -> Bool {
        // Changes are concurrent if neither happened before the other
        !change1.happensBefore(change2) && !change2.happensBefore(change1)
    }
 
    func mergeConcurrentChanges(
        local: VectorClockElement,
        remote: VectorClockElement
    ) -> VectorClockElement {
        // For concurrent changes, implement application-specific merge logic
        // Example: merge by choosing alphabetically first value
        let mergedValue = [local.value, remote.value].sorted().first ?? local.value
 
        var mergedClock = local.vectorClock
        for (clientId, time) in remote.vectorClock {
            mergedClock[clientId] = max(mergedClock[clientId] ?? 0, time)
        }
 
        return VectorClockElement(
            value: mergedValue,
            vectorClock: mergedClock,
            clientId: local.clientId
        )
    }
}

class SemanticConflictResolver {
    // For document-like data (text, lists)
    func resolveTextConflict(
        local: String,
        remote: String,
        original: String
    ) -> String {
        // Three-way merge approach
 
        // Check if only one side changed
        if local == original {
            return remote // Remote side won
        }
        if remote == original {
            return local // Local side won
        }
 
        // Both sides changed - need operational transformation or CRDTs
        // Fallback: prefer longer content (less data loss)
        return local.count >= remote.count ? local : remote
    }
 
    // For list items
    func resolveListConflict(
        local: [String],
        remote: [String],
        original: [String]
    ) -> [String] {
        // Use longest common subsequence to detect what actually changed
        let lcs = longestCommonSubsequence(original, local)
        let remoteChanges = detectChanges(original, remote)
 
        // Apply remote changes to local result
        var merged = local
        for change in remoteChanges {
            if !merged.contains(change.newValue) {
                merged.append(change.newValue)
            }
        }
 
        return merged
    }
 
    // For numeric fields
    func resolveNumericConflict(
        local: Double,
        remote: Double,
        original: Double
    ) -> Double {
        let localChange = local - original
        let remoteChange = remote - original
 
        // Apply both changes (addition is commutative)
        return original + localChange + remoteChange
    }
}

class ConflictPrompt {
    struct Conflict {
        let entityId: String
        let fieldName: String
        let localValue: Any
        let remoteValue: Any
        let timestamp: Date
    }
 
    func presentConflictUI(
        conflicts: [Conflict],
        onResolve: @escaping ([String: Any]) -> Void
    ) {
        // Build resolution UI with side-by-side comparison
        // User selects which version to keep or manually edits
        var resolutions: [String: Any] = [:]
 
        for conflict in conflicts {
            // Present UI for user to choose
            let userChoice = showResolutionDialog(conflict)
            resolutions[conflict.entityId] = userChoice
        }
 
        onResolve(resolutions)
    }
 
    private func showResolutionDialog(_ conflict: Conflict) -> Any {
        // In real implementation, present SwiftUI modal
        // For now, return a resolved value
        conflict.remoteValue // Example: prefer remote
    }
}

class ProductionSyncEngine {
    private let localStore: LocalDataStore
    private let networkService: NetworkService
    private let conflictResolver: SemanticConflictResolver
    private var syncState = SyncState()
 
    struct SyncState {
        var lastSyncTime: Date?
        var isSyncing = false
        var pendingChangeCount = 0
        var lastSyncError: Error?
    }
 
    // Automatic sync on network availability
    func setupNetworkObserver() {
        NotificationCenter.default.addObserver(
            forName: NSNotification.Name.reachabilityChanged,
            object: nil,
            queue: .main
        ) { [weak self] _ in
            Task {
                try? await self?.syncWhenNeeded()
            }
        }
    }
 
    // Smart sync: batch changes and deduplicate
    func recordChange(_ change: EntityChange) async throws {
        try await localStore.saveChanges([change])
        syncState.pendingChangeCount += 1
 
        // Trigger sync after a delay (debounce)
        try await Task.sleep(nanoseconds: 2_000_000_000) // 2 seconds
        try await syncWhenNeeded()
    }
 
    // Main sync loop
    func syncWhenNeeded() async throws {
        guard !syncState.isSyncing else { return }
        guard networkAvailable() else { return }
 
        syncState.isSyncing = true
        defer { syncState.isSyncing = false }
 
        do {
            // Step 1: Get pending changes from local store
            let pendingChanges = try await localStore.getPendingChanges()
            guard !pendingChanges.isEmpty else { return }
 
            // Step 2: Batch and deduplicate
            let batchedChanges = batchAndDeduplicate(pendingChanges)
 
            // Step 3: Send to server
            let response = try await networkService.sync(
                clientChanges: batchedChanges,
                lastSyncTime: syncState.lastSyncTime
            )
 
            // Step 4: Resolve conflicts
            let resolvedChanges = try resolveConflicts(
                local: batchedChanges,
                remote: response.serverChanges
            )
 
            // Step 5: Merge remote changes
            try await applyRemoteChanges(response.serverChanges)
 
            // Step 6: Mark changes as synced
            try await markAsSynced(batchedChanges)
 
            syncState.lastSyncTime = Date()
            syncState.lastSyncError = nil
 
        } catch {
            syncState.lastSyncError = error
            throw error
        }
    }
 
    private func batchAndDeduplicate(_ changes: [EntityChange]) -> [EntityChange] {
        var batchedMap: [String: EntityChange] = [:]
 
        for change in changes {
            // Keep only the latest change per entity
            batchedMap[change.entityId] = change
        }
 
        return Array(batchedMap.values)
    }
 
    private func resolveConflicts(
        local: [EntityChange],
        remote: [EntityChange]
    ) -> [EntityChange] {
        var resolved: [String: EntityChange] = [:]
 
        // Create map of remote changes by entity ID
        let remoteMap = Dictionary(grouping: remote) { $0.entityId }
 
        // Process all changes
        for change in local + remote {
            let key = change.entityId
 
            if let remoteChange = remoteMap[key]?.first {
                // Conflict detected - resolve using strategy
                let winner = conflictResolver.resolveConflict(
                    local: change,
                    remote: remoteChange
                )
                resolved[key] = winner
            } else {
                resolved[key] = change
            }
        }
 
        return Array(resolved.values)
    }
 
    private func networkAvailable() -> Bool {
        // Check network status
        true // Simplified
    }
}

// Mock network service for testing
class MockNetworkService: NetworkService {
    enum NetworkCondition {
        case online
        case offline
        case slowConnection(delaySeconds: Double)
        case flaky(successRate: Double)
    }
 
    var condition: NetworkCondition = .online
    var syncHistory: [SyncRequest] = []
 
    func sync(clientChanges: [EntityChange], lastSyncTime: Date?) async throws -> SyncResponse {
        syncHistory.append(SyncRequest(changes: clientChanges, time: lastSyncTime ?? Date()))
 
        switch condition {
        case .offline:
            throw NetworkError.noConnection
 
        case .slowConnection(let delay):
            try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
            return SyncResponse(serverChanges: [], conflicts: [])
 
        case .flaky(let successRate):
            if Double.random(in: 0...1) > successRate {
                throw NetworkError.timeout
            }
            return SyncResponse(serverChanges: [], conflicts: [])
 
        case .online:
            return SyncResponse(serverChanges: [], conflicts: [])
        }
    }
}
 
// Test offline changes are tracked
func testOfflineChangesArePersisted() async throws {
    let store = try RealmOfflineStore()
    let syncEngine = ProductionSyncEngine(localStore: store, networkService: MockNetworkService())
 
    // Record change while offline
    let change = EntityChange(
        entityId: "task-1",
        entityType: "Task",
        operation: .create,
        timestamp: Date(),
        data: AnyCodable(["title": "Offline Task"]),
        clientId: UIDevice.current.identifierForVendor?.uuidString ?? ""
    )
 
    try await syncEngine.recordChange(change)
 
    // Verify change is in local store
    let pendingChanges = try await store.getPendingChanges()
    XCTAssertEqual(pendingChanges.count, 1)
    XCTAssertEqual(pendingChanges.first?.entityId, "task-1")
}
 
// Test conflict resolution
func testConflictResolution() async throws {
    let resolver = SemanticConflictResolver()
 
    let local = "Updated text locally"
    let remote = "Updated text remotely"
    let original = "Original text"
 
    let resolved = resolver.resolveTextConflict(
        local: local,
        remote: remote,
        original: original
    )
 
    // Verify resolution picked one of the changes
    XCTAssertTrue([local, remote].contains(resolved))
}

class OptimizedOfflineStore {
    func setupOptimizedSchema() throws {
        // Create indices on frequently queried fields
        try db.create(
            index: "idx_task_status_date",
            on: "tasks",
            indexesBy: ["status", "createdAt"]
        )
 
        // Separate index for sync-related queries
        try db.create(
            index: "idx_pending_sync",
            on: "tasks",
            indexesBy: ["isSynced", "lastModified"]
        )
    }
 
    func queryPendingChanges(limit: Int = 100) async throws -> [EntityChange] {
        // Uses index for fast lookups
        return try db.selectAll(
            from: EntityChange.self,
            where: ("isSynced" == false).order(by: "timestamp".asColumn(), .ascending),
            limit: limit
        )
    }
}

class StreamingOfflineStore {
    // Stream large result sets to avoid memory overload
    func streamPendingChanges(
        batchSize: Int = 500,
        onBatch: @escaping ([EntityChange]) -> Void
    ) async throws {
        var offset = 0
        var hasMore = true
 
        while hasMore {
            let batch = try db.selectAll(
                from: EntityChange.self,
                where: "isSynced" == false,
                limit: batchSize,
                offset: offset
            )
 
            hasMore = batch.count == batchSize
            onBatch(batch)
            offset += batchSize
        }
    }
}

class LargeFileSync {
    // Chunk large files for reliable sync
    func uploadLargeFile(
        fileURL: URL,
        chunkSize: Int = 5_000_000 // 5MB chunks
    ) async throws {
        let fileSize = try FileManager.default.attributesOfItem(atPath: fileURL.path)[.size] as? Int ?? 0
        let fileId = UUID().uuidString
 
        var offset = 0
        while offset < fileSize {
            let remainingSize = fileSize - offset
            let currentChunkSize = min(chunkSize, remainingSize)
 
            let chunk = try readChunk(fileURL, offset: offset, size: currentChunkSize)
 
            try await networkService.uploadChunk(
                fileId: fileId,
                chunkIndex: offset / chunkSize,
                totalChunks: (fileSize + chunkSize - 1) / chunkSize,
                data: chunk
            )
 
            offset += currentChunkSize
        }
    }
}

class DeletionTracking {
    // Mark for deletion instead of immediate removal
    func markForDeletion(_ entityId: String) async throws {
        let deleteChange = EntityChange(
            entityId: entityId,
            entityType: "Task",
            operation: .delete,
            timestamp: Date(),
            data: AnyCodable([:]),
            clientId: clientId
        )
 
        try await localStore.saveChanges([deleteChange])
        // Keep record in local store until sync confirms deletion
    }
 
    // Only truly delete after successful sync
    func purgeDeletedEntities(afterSyncingAt date: Date) async throws {
        try await localStore.deleteChanges(
            where: NSPredicate(format: "operation == %@ AND syncedAt < %@", "delete", date as NSDate)
        )
    }
}

// Recommended: SQLite WAL mode + explicit checkpoint
let connection = try Connection(dbPath)
try connection.execute("PRAGMA journal_mode=WAL;")
try connection.execute("PRAGMA synchronous=NORMAL;")
try connection.transaction {
    try connection.run(favorites.insert(or: .replace, item))
}
// Transactions auto-commit, but when you want to force the sync explicitly:
try connection.execute("PRAGMA wal_checkpoint(PASSIVE);")

class AdOfflineFallback {
    private var retryAttempts = 0
    private let maxRetries = 3
 
    func loadAd() {
        guard Reachability.shared.isConnected else {
            bannerView.isHidden = true
            heightConstraint.constant = 0
            return
        }
        bannerView.load(GADRequest())
    }
 
    func handleAdFailedToLoad(_ error: Error) {
        guard retryAttempts < maxRetries else { return }
        let delay = pow(2.0, Double(retryAttempts)) * 5.0
        DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
            self?.retryAttempts += 1
            self?.loadAd()
        }
    }
}