1 contributor
CloudKit Sync - Visual Reference
System Architecture Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ USB Meter App │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────────────────┐ │
│ │ Meter.swift │ │ BluetoothManager.swift │ │
│ │ (UI + State) │◄────────│ (BT Communication) │ │
│ └────────┬─────────┘ └─────────────────────────────────┘ │
│ │ │
│ │ operationalState changes │
│ │ (connect/disconnect) │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ AppData │ │
│ │ (Global Sync Orchestrator) │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ • publishMeterConnection(mac, type) │ │
│ │ • clearMeterConnection(mac) │ │
│ │ • reloadSettingsFromCloudStore() │ │
│ │ • setupRemoteChangeNotificationObserver() │ │
│ └────────┬──────────────────────────┬──────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌────────────────────────┐ │
│ │ CloudDeviceSettings │ │ NSManagedObjectContext │ │
│ │ Store │ │ (viewContext) │ │
│ │ (CR operations) │ └────────────────────────┘ │
│ └────────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ NSPersistentCloudKitContainer │ │
│ │ (Automatic sync layer) │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ • Detects changes │ │
│ │ • Queues for CloudKit │ │
│ │ • Receives remote notifications │ │
│ │ • Applies merge policy │ │
│ └──────────────┬──────────────────────┬────────────────┘ │
│ │ │ │
└────────────────┼──────────────────────┼──────────────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Local SQLite DB │ │ Persistent History │
│ (DeviceSettings) │ │ Journal │
└───────────────────┘ └──────────────────────┘
│ │
└──────────┬───────────┘
│
┌──────────▼────────────┐
│ CloudKit Framework │
│ (Device background │
│ process) │
└──────────┬────────────┘
│
[Network Sync]
│
┌──────────▼────────────┐
│ iCloud Servers │
│ CloudKit Database │
└──────────┬────────────┘
│
┌──────────▼──────────────────┐
│ Other Devices (iPhone, │
│ iPad, Mac) on same │
│ iCloud account │
└─────────────────────────────┘
Local Write Flow (Sequence Diagram)
Device A AppData Core Data CloudKit
│ │ │ │
│─ User connects ───►│ │ │
│ meter │ │ │
│ │─ setConnection() ───►│ │
│ │ (foreground QoS) │ │
│ │ │ │
│◄─ UI Updates │◄─ @Published change │ │
│ (local) │ (immediate) │ │
│ │ │ │
│ │─ context.save() ────►│ │
│ │ │ │
│ │ │─ Detect change │
│ │ │─ Create CKRecord │
│ │ │─ Queue for sync ─►│
│ │ │ │─ Network upload
│ │ │ │ (1-2s)
│ │ │ │
┼────────────────────┼──────────────────────┼──────────────────┼───► [iCloud Server]
│ │ │ │
│ (Device B receives remote change notification after ~5s) │
Remote Change Reception (Sequence Diagram)
Device B System iOS Core Data AppData
│ │ │ │
│ [iCloud notifies] │ │
│ │ │ │
│ │─ Remote change ─────►│ │
│ │ notification posted │ │
│ │ │ │
│ │ │─ Merge changes │
│ │ │ (merge policy) │
│ │ │─ Save locally │
│ │ │ │
│ │─ NSPersistentStore ─►│─ remoteStoreDidChange()
│ │ RemoteChange │ │
│ │ notification │ │
│ │ │ │
│ │ │◄─ reloadSettings()
│ │ │ FromCloudStore()
│◄─ UI updates ◄───────────────────────────────────────────────
│ "Connected on │
│ Device A" │
Connection Lock Lifecycle
t=0s: Device A connects
┌─────────────────────────────────────┐
│ connectedByDeviceID = UUID_A │
│ connectedByDeviceName = "iPhone A" │
│ connectedAt = 2025-03-26 10:00:00 │
│ connectedExpiryAt = 10:02:00 │ ◄─ TTL = 120s
└─────────────────────────────────────┘
│
│ [CloudKit syncs]
▼
[Device B sees connection]
"Meter locked by iPhone A"
t=60s: Device A still connected
(TTL still valid)
t=120s: Connection expires
┌─────────────────────────────────────┐
│ connectedExpiryAt = 10:02:00 │
│ now() > connectedExpiryAt ✓ │
└─────────────────────────────────────┘
│
[Device B checks expiry]
│
if (now > connectedExpiryAt)
Device B can connect!
Merge Conflict Resolution
Device A Device B
t=0.5s: Sets meterName t=0.6s: Sets meterName
"Kitchen Meter" "Charger Meter"
│ │
▼ ▼
Save & Queue Save & Queue
│ │
└───────────┬────────────────────┘
▼
[Both pushed to CloudKit]
(Race condition)
CloudKit Merge Policy:
NSMergeByPropertyStoreTrumpMergePolicy
→ Latest write wins
Result on both devices:
✗ One value reverts (~1s after cloud update)
✓ No data loss, eventually consistent
Rebuild Flow (v2 → v3)
User launches app (v3)
│
▼
AppDelegate.didFinishLaunchingWithOptions
│
▼
rebuildCanonicalStoreIfNeeded(version: 3)
│
├─ Check UserDefaults["cloudStoreRebuildVersion.3"]
│
├─ if already done:
│ return (skip)
│
└─ if not done:
│
├─ Fetch all DeviceSettings records
│
├─ Group by normalized macAddress
│
├─ For each group:
│ ├─ Find "winner" (most data + most recent)
│ └─ Merge others INTO winner
│ └─ Delete duplicates
│
├─ context.save()
│ (CloudKit propagates deletes)
│
├─ UserDefaults["cloudStoreRebuildVersion.3"] = true
│
└─ ✓ Done (won't run again)
State Machine: Meter Connection
┌─────────────────┐
│ OFFLINE │ ◄──────────────────────────────┐
└────────┬────────┘ │
│ │
advertisment heard
│
▼
┌─────────────────────────────┐
│ PERIPHERAL_NOT_CONNECTED │
└────────┬────────────────────┘
│
user clicks "Connect"
Meter.connect() called
│
▼
┌─────────────────────────────┐
│ PERIPHERAL_CONNECTION_PD │
└────────┬────────────────────┘
│
BT services discovered
│
▼
┌─────────────────────────────┐
│ PERIPHERAL_CONNECTED │
│ (appData.publishMeterConn)│ ◄─────── CloudKit SyncStart
└────────┬────────────────────┘
│
peripheral ready for commands
│
▼
┌─────────────────────────────┐
│ PERIPHERAL_READY │
└────────┬────────────────────┘
│
data request sent
│
▼
┌─────────────────────────────┐
│ COMMUNICATING │
└────────┬────────────────────┘
│
data received
│
▼
┌─────────────────────────────┐
│ DATA_IS_AVAILABLE │ ──────── Cloud Polling Loop
└─────────────────────────────┘ (every 60s renew connection)
│
connect lost / timeout
│
▼ (Or clear in UI)
OFFLINE again
Connection Renewal (Heartbeat)
┌─────────────────────────────┐
│ Meter.connect() called │
│ operationalState changed │
│ → .peripheralConnected │
└──────────┬──────────────────┘
│
▼
startConnectionRenewal()
│
├─ Create timer: interval = 60s
│
└─ repeats every 60s:
│
├─ appData.publishMeterConnection()
│ (updates connectedAt + connectedExpiryAt)
│
└─ CloudKit syncs (keeps lock alive)
Disconnection:
┌─────────────────────────────┐
│ operationalState changed │
│ → .offline / .notConnected │
└──────────┬──────────────────┘
│
▼
stopConnectionRenewal()
│
├─ connectionRenewalTimer.invalidate()
│
└─ appData.clearMeterConnection()
(removes connectedByDeviceID)
│
└─ CloudKit syncs (lock released)
Error Recovery Paths
┌─────────────────────┐
│ Normal Operation │
└─────────────────────┘
│
▼ [Error: CloudKit unavailable]
┌──────────────────────────────┐
│ Queue changes locally │
│ (stored in SQLite) │
└──────────────────────────────┘
│
▼ [Network restored]
┌──────────────────────────────┐
│ NSPersistentCloudKit │
│ resumes sync automatically │
└──────────────────────────────┘
│
▼
┌─────────────────────┐
│ Back to normal │
└─────────────────────┘
┌─────────────────────┐
│ Collision detected │ (Device A & B both edited same field)
└─────────────────────┘
│
▼
┌──────────────────────────────┐
│ NSMergeByPropertyStoreTrump │
│ (CloudKit version wins) │
└──────────────────────────────┘
│
└─ User sees local change revert ~1s after
cloud update arrives (rare, acceptable)