Synchronizing documents in the iCloud environment

At a glance

Project structure

Source bundle/
└── SimpleiCloudDocument/
    ├── AppDelegate.swift
    ├── Main/
    │   ├── MainViewController.swift
    │   ├── MetadataProvider.swift
    │   ├── MainViewController+TableView.swift
    │   └── DiffableMetadataSource.swift
    ├── Detail/
    │   ├── DetailViewController.swift
    │   ├── ImageViewController.swift
    │   ├── DetailViewController+CollectionView.swift
    │   ├── Document.swift
    │   ├── ImageCVCell.swift
    │   └── DiffableImageSource.swift
    └── SceneDelegate.swift

Structure observations

• The Main slice owns container discovery and the document list; the Detail slice owns an open document and its images/conflicts.
• MetadataProvider converts Foundation query notifications into app-specific metadata updates on the main queue.
• Document serializes package-wrapper and pending-change access with a private concurrent queue and barrier writes.

Overall architecture

flowchart LR
    ICLOUD["iCloud container"] --> QUERY["MetadataProvider / NSMetadataQuery"]
    QUERY --> NOTICE["sicdMetadataDidChange notification"]
    NOTICE --> MAIN["MainViewController"]
    MAIN --> LIST["DiffableMetadataSource snapshot"]
    LIST --> SELECT["Selected MetadataItem URL"]
    SELECT --> DOC["Document UIDocument"]
    DOC --> DETAIL["DetailViewController"]
    DETAIL --> IMAGES["DiffableImageSource and conflict UI"]
    DOC --> COORD["Coordinated package read/write and peer changes"]

Reference code

SimpleiCloudDocument/Main/MetadataProvider.swift:52 — query-notification adapter

        let names: [NSNotification.Name] = [
            .NSMetadataQueryDidFinishGathering, .NSMetadataQueryDidUpdate
        ]
        let publishers = names.map { NotificationCenter.default.publisher(for: $0) }
        querySubscriber = Publishers.MergeMany(publishers)
            .receive(on: DispatchQueue.main).sink { notification in
                guard notification.object as? NSMetadataQuery === self.metadataQuery else { return }
                let userInfo: MetadataDidChangeUserInfo = [.queryResults: self.metadataItemList()]
                NotificationCenter.default.post(name: .sicdMetadataDidChange,
                                                object: self, userInfo: userInfo)
            }

Interpretation

Metadata discovery and document content are separate lifecycles. The provider reports which URLs exist; the main controller snapshots that read model. Only after navigation does the detail controller own an open UIDocument, whose subclass governs package serialization and peer-change reconciliation.

Ownership and state

classDiagram
    MainViewController *-- MetadataProvider : creates
    MainViewController *-- DiffableMetadataSource : lazy
    MetadataProvider *-- NSMetadataQuery : private
    MetadataProvider *-- AnyCancellable : private
    DetailViewController o-- Document : assigned for selected URL
    Document *-- DispatchQueue : private accessQueue
    Document *-- FileWrapperMap : package state
    ImageCVCell o-- ImagCVCellDelegate : weak

Ownership evidence

SimpleiCloudDocument/Main/MainViewController.swift:15 — main-list collaborators

    private(set) var metadataProvider: MetadataProvider?

    lazy var diffableMetadataSource: DiffableMetadataSource! = {
        DiffableMetadataSource(tableView: tableView) { tableView, indexPath, metadata in
            let cell = tableView.dequeueReusableCell(
                withIdentifier: "UITableViewCell", for: indexPath)
            cell.textLabel!.text = metadata.url.lastPathComponent
            return cell
        }
    }()

Composition denotes source-visible construction and retained value state. Aggregation denotes a stored or injected collaborator whose exclusive lifetime the source does not prove.

Class and protocol design

SimpleiCloudDocument/Detail/ImageCVCell.swift:10 — local cell-action contract

protocol ImagCVCellDelegate: AnyObject {
    func deleteCell(_ cell: UICollectionViewCell)
}

class ImageCVCell: UICollectionViewCell {
    weak var delegate: ImagCVCellDelegate?

    @IBAction func deleteAction(_ sender: UIButton) {
        delegate?.deleteCell(self)
    }
}

ImagCVCellDelegate is a local, class-bound protocol and its weak property makes the non-ownership explicit. UIDocument and collection/table protocols remain framework callback boundaries.

Access control

Reference code

SimpleiCloudDocument/Detail/Document.swift:34 — private synchronized document storage

    private lazy var accessQueue: DispatchQueue = {
        DispatchQueue(label: "Document", attributes: .concurrent)
    }()

    private var _fileWrappersUnderRoot: [String: FileWrapper]?
    private var _unsavedUserChanges = Changes()

    private(set) var unpresentedPeerChanges = Changes()

private(set) communicates split authority directly: broad read access with restricted mutation. No public, open, or fileprivate feature surface is required for this single app target.

Logic ownership and placement

Design patterns

Naming conventions

• Types identify layer roles (MetadataProvider, Document, DiffableMetadataSource, DetailViewController).
• Private backing storage uses an underscore only where synchronized computed accessors wrap it.
• Notification names are sample-prefixed (sicdMetadataDidChange) and user-info keys are strongly typed.
• Files group controller responsibilities into focused extensions such as Document, Conflict, CollectionView, and ImagePicker.

Architecture takeaways

• Treat metadata discovery as a read model and an open UIDocument as a separate content session.
• Use private(set) when collaborators need state visibility but must not replace the authority-owned value.
• Keep package state behind serialized private access and use coordinated writes for external file operations.

Source map

• Official Apple documentation