Sync Architecture

Overview of TheCompanyApp's CloudKit integration, dual-store model, and synchronization strategy.

CloudKit Container

Container ID: iCloud.TheCompany.3N

Databases:

• Private Database: User's own companies and credentials

• Shared Database: Companies shared by other users

• Public Database: Not used

Dual-Store Architecture

┌─────────────────────────────────────────────┐
│        NSPersistentCloudKitContainer        │
└───────────┬─────────────────┬───────────────┘
            │                 │
     ┌──────▼──────┐   ┌──────▼──────────┐
     │Private Store│   │  Shared Store   │
     │  (default)  │   │ (configuration) │
     └──────┬──────┘   └──────┬──────────┘
            │                 │
     ┌──────▼──────┐   ┌──────▼──────────┐
     │   Private   │   │     Shared      │
     │  Database   │   │    Database     │
     └─────────────┘   └─────────────────┘
            CloudKit Container

Store Configuration

Private Store:

• File: TheCompanyApp.sqlite

• CloudKit Options: databaseScope = .private

• Contains:

  • Companies owned by user

  • UserPass for all companies

  • AccessControl

  • All owned company data

Shared Store:

• File: TheCompanyApp-shared.sqlite

• Configuration: "Shared"

• CloudKit Options: databaseScope = .shared

• Contains:

  • Companies shared by others

  • Shared company data (inventory, orders, etc.)

  • AccessControl for participants

Code Implementation

File: Persistence.swift

// Private Store
let privateStore: NSPersistentStoreDescription
privateStore.url = storeURL.appendingPathComponent("TheCompanyApp.sqlite")
let privateOptions = NSPersistentCloudKitContainerOptions(containerIdentifier: "iCloud.TheCompany.3N")
privateOptions.databaseScope = .private
privateStore.cloudKitContainerOptions = privateOptions

// Shared Store
let sharedStore = NSPersistentStoreDescription()
sharedStore.url = storeURL.appendingPathComponent("TheCompanyApp-shared.sqlite")
sharedStore.configuration = "Shared"
let sharedOptions = NSPersistentCloudKitContainerOptions(containerIdentifier: "iCloud.TheCompany.3N")
sharedOptions.databaseScope = .shared
sharedStore.cloudKitContainerOptions = sharedOptions

container.persistentStoreDescriptions = [privateStore, sharedStore]

Automatic Sync

CloudKit syncs automatically when:

• context.save() is called

• App becomes active

• Remote changes occur (push notifications)

• Periodic background fetch

Sync is Non-Blocking

func saveAsync() {
    guard hasChanges else { return }
    
    Task.detached(priority: .userInitiated) { [weak self] in
        await self?.perform {
            try self?.save()
        }
    }
}

User doesn't wait for CloudKit upload; it happens in background.

CKShare for Collaboration

When owner shares a company:

// Create CKShare for Companies record
let (_, share) = try await container.share([company], to: nil)

// Enlist all related data
let items = fetchAllCompanyData(company.companyID)
try await container.share(items, to: share)

Result:

• CKShare created in Private Database

• Share zone created

• Participants access via Shared Database

Synchronization Guarantees

Eventual Consistency: Changes sync within seconds to minutes, not instant.

Conflict Resolution: Last-write-wins at property level.

Offline Queue: Changes saved locally, sync when connection restored.

---

Related: Private Store, Shared Store, Sharing Flow