axiom-cloud-sync

# Cloud Sync

## Overview

**Core principle**: Choose the right sync technology for the data shape, then implement offline-first patterns that handle network failures gracefully.

Two fundamentally different sync approaches:
- **CloudKit** — Structured data (records with fields and relationships)
- **iCloud Drive** — File-based data (documents, images, any file format)

## Quick Decision Tree

```
What needs syncing?

├─ Structured data (records, relationships)?
│  ├─ Using SwiftData? → SwiftData + CloudKit (easiest, iOS 17+)
│  ├─ Need shared/public database? → CKSyncEngine or raw CloudKit
│  └─ Custom persistence (GRDB, SQLite)? → CKSyncEngine (iOS 17+)
│
├─ Documents/files users expect in Files app?
│  └─ iCloud Drive (UIDocument or FileManager)
│
├─ Large binary blobs (images, videos)?
│  ├─ Associated with structured data? → CKAsset in CloudKit
│  └─ Standalone files? → iCloud Drive
│
└─ App settings/preferences?
   └─ NSUbiquitousKeyValueStore (simple key-value, 1MB limit)
```

## CloudKit vs iCloud Drive

| Aspect | CloudKit | iCloud Drive |
|--------|----------|--------------|
| **Data shape** | Structured records | Files/documents |
| **Query support** | Full query language | Filename only |
| **Relationships** | Native support | None (manual) |
| **Conflict resolution** | Record-level | File-level |
| **User visibility** | Hidden from user | Visible in Files app |
| **Sharing** | Record/database sharing | File sharing |
| **Offline** | Local cache required | Automatic download |

## Red Flags

If ANY of these appear, STOP and reconsider:

- ❌ "Store JSON files in CloudKit" — Wrong tool. Use iCloud Drive for files
- ❌ "Build relationships manually in iCloud Drive" — Wrong tool. Use CloudKit
- ❌ "Assume sync is instant" — Network fails. Design offline-first
- ❌ "Skip conflict handling" — Conflicts WILL happen on multiple devices
- ❌ "Use CloudKit for user documents" — Users can't see them. Use iCloud Drive
- ❌ "Sync on app launch only" — Users expect continu