# CloudKit Sync Documentation

Complete reference for USB Meter's multi-device synchronization system using CloudKit.

---

## Quick Start

**Problem:** How do settings sync across my iPhone, iPad, and Mac?

**Answer:**

1. When you connect a meter on iPhone → `Meter.swift` calls `appData.publishMeterConnection()`

2. This updates a **DeviceSettings** record in Core Data

3. `NSPersistentCloudKitContainer` automatically syncs it to iCloud

4. Your iPad + Mac receive a notification → refresh UI

5. Within 2-5 seconds, all devices show "Connected on iPhone"

---

## Documentation Files

### 1. **SCHEMA.md** — Data Model & Structure

- DeviceSettings entity attributes

- CloudKit record mapping

- Why `uniquenessConstraint` was removed

- Version history (v1 → v2 → v3)

**Read this if:** You need to understand the data structure, add fields, or debug data corruption.

### 2. **MECHANISM.md** — How Sync Works

- Complete architecture diagram

- Step-by-step local write flow

- Remote change reception flow

- Core AppData methods explained

- Connection lifecycle (TTL, expiry, locking)

- Error handling & recovery

**Read this if:** You're troubleshooting sync issues, understanding threading, or extending functionality.

### 3. **TROUBLESHOOTING.md** — Debugging Guide

- Configuration verification checklist

- Common issues & fixes

- Real-time monitoring code

- Performance benchmarks

- Log analysis

**Read this if:** Sync isn't working, you want to add debug UI, or need production troubleshooting.

---

## Key Concepts

### DeviceSettings Record

Represents a single Bluetooth meter device with its metadata:

```

macAddress: "aa:bb:cc:dd:ee:ff"  ← identifies the meter

meterName: "Kitchen Meter"        ← user-friendly name

modelType: "TC66C"                ← hardware type

connectedByDeviceID: "UUID"       ← which device is using it now

connectedExpiryAt: Date           ← connection lock TTL (120s)

updatedAt: Date                   ← last sync timestamp

```

### Sync Heartbeat

- **Connect:** `publishMeterConnection()` → saves record → syncs

- **Disconnect:** `clearMeterConnection()` → clears record → syncs

- **Refresh:** Periodically calls `reloadSettingsFromCloudStore()` to check for remote changes

### Conflict Resolution

If Device A and B edit the same record simultaneously:

- **Policy:** `NSMergeByPropertyStoreTrumpMergePolicy`

- **Rule:** CloudKit's version always wins

- **Edge case:** User might see their local change revert (~1s after)

---

## Architecture Summary

```

Meter UI ──→ BT Connection ──→ AppData ──→ CloudDeviceSettingsStore ──→ Core Data

                                  ↓                ↓

                          [CloudKit Sync]   [persisted locally]

                                  ↓

                          [iCloud Servers]

                                  ↓

                          Other Devices ──→ UI Updates

```

---

## Critical Files in Codebase

| File | Role |

|------|------|

| `AppDelegate.swift` | Creates `NSPersistentCloudKitContainer` (line 85-127) |

| `SceneDelegate.swift` | Calls `activateCloudDeviceSync()` at startup |

| `AppData.swift` | Orchestrates sync: `publishMeterConnection`, `clearMeterConnection`, `reloadSettingsFromCloudStore` |

| `Meter.swift` | Line 109, 118, 132: Calls `appData` methods on state changes |

| `CKModel.xcdatamodeld/USB_Meter 2.xcdatamodel/contents` | Core Data schema (no uniqueness constraint) |

| `USB Meter.entitlements` | iCloud container + CloudKit permissions |

---

## Debugging Checklist

- [ ] CloudKit account status = `.available`?

- [ ] Entitlements file includes `iCloud.ro.xdev.USB-Meter`?

- [ ] Model version is `USB_Meter 2.xcdatamodel` or later?

- [ ] `cloudStoreRebuildVersion` ≥ 3?

- [ ] Remote change observer registered in `setupRemoteChangeNotificationObserver()`?

- [ ] Merge policy = `NSMergeByPropertyStoreTrumpMergePolicy`?

---

## Common Workflows

### "Settings won't sync to my other device"

1. Check CloudKit account (TROUBLESHOOTING.md § 1)

2. Verify entitlements (TROUBLESHOOTING.md § 2)

3. Force reload: `appData.reloadSettingsFromCloudStore()`

4. Check logs for `NSPersistentStoreRemoteChange` notifications

### "I see duplicate meter entries"

1. Verify `cloudStoreRebuildVersion = 3` deployed

2. Check `rebuildCanonicalStoreIfNeeded` ran (UserDefaults `cloudStoreRebuildVersion.3`)

3. If duplicates persist, see TROUBLESHOOTING.md § Issue 2

### "Connection lock doesn't expire"

1. Check system clock on Device A (ParentalControls?)

2. Manual unlock: `appData.clearMeterConnection(mac: "...")`

3. Verify TTL is 120s in `setConnection()`

### "I need to add a new sync field"

1. Edit `USB_Meter 2.xcdatamodel/contents` → add attribute (optional!)

2. Bump Core Data version if needed (lightweight migration)

3. Update `CloudDeviceSettingsStore` to populate it

4. Sync resumes automatically

---

## Performance

- **Local write latency:** ~10ms

- **CloudKit network push:** ~1-2s (typical)

- **Remote notification delivery:** ~2-5s

- **UI update after notification:** <100ms

- **Full reload (10 records):** ~50ms

Total end-to-end for a setting change: **~5-8 seconds** (typical, good network)

---

## Testing Tips

Use two devices on same iCloud account:

1. **Connect meter on iPhone** → Check iPad within 5s for "Connected on iPhone"

2. **Rename meter on iPhone** → Name updates on iPad instantly (local) after sync

3. **Airplane mode iPhone** → Changes queue locally

4. **Reconnect iPhone** → Changes resync automatically

5. **Switch iCloud accounts** → No data loss (encrypted in CloudKit)

---

## References

- [NSPersistentCloudKitContainer docs](https://developer.apple.com/documentation/coredata/nspersistentcloudkitcontainer)

- [CloudKit best practices](https://developer.apple.com/documentation/cloudkit/best_practices)

- [Core Data concurrency](https://developer.apple.com/documentation/coredata/concurrency)

- [Merging edited Core Data objects](https://developer.apple.com/documentation/coredata/nsmergepolicy)

---

## Questions?

Refer to specific sections above by file, or check the troubleshooting checklist in TROUBLESHOOTING.md.