Sharing Company

Complete guide to sharing your company with team members using CloudKit sharing.

Overview

TheCompanyApp's company sharing enables real-time collaboration where:

• Owners create and share companies with team members

• Participants access shared company data on their devices

• CloudKit handles synchronization automatically

• Security ensures only invited users can access data

Prerequisites

For Company Owners

Before sharing:

• ✅ Company created and fully set up

• ✅ Business or Enterprise tier (Free tier cannot share)

• ✅ Owner device connected to internet

• ✅ Participants have Apple IDs and TheCompanyApp installed

For Participants

Before accepting:

• ✅ TheCompanyApp installed

• ✅ Signed in to iCloud

• ✅ Received share invitation (link)

• ✅ Internet connection

Tier Limitations

Tier	Sharing Allowed	Max Participants
Free	❌ No	0 (owner only)
Business	✅ Yes	Up to 10
Enterprise	✅ Yes	Unlimited

Upgrade Prompt: If you try to share on Free tier, app will prompt to upgrade.

Sharing Flow (Owner)

Step 1: Navigate to Share Settings

1. Select Company to share

2. Settings tab → "Share Company" or "Sharing"

3. Share settings screen appears (ShareAppView.swift)

Step 2: Initiate Sharing

First Time Sharing:

1. Tap "Share Company" button

2. App creates CKShare if not already exists

What Happens Internally:

The app (ChoosVersionView.swift → createCKShareIfNeeded()):

// 1. Get the Companies record (share root)
let company = selectedCompany

// 2. Determine correct store
let rootStore = company.objectID.persistentStore

// 3. Check if CKShare already exists
if let existingShare = try? container.fetchShares(matching: [company.objectID])[company.objectID] {
    // Share already exists, use it
    presentShareController(with: existingShare)
} else {
    // 4. Create new CKShare
    let (savedObjects, share) = try await container.share([company], to: nil)
    
    // 5. Enlist all existing company data into share
    let relatedObjects = fetchAllCompanyData(for: company)
    try await container.share(relatedObjects, to: share)
    
    presentShareController(with: share)
}

Enlistment: All existing inventory, orders, contacts, etc. are enlisted into the CKShare zone so participants can see them.

Step 3: Share Controller

iOS presents UICloudSharingController:

Share Options:

• Anyone with the link: Any user with link can join

• Only people you invite: Requires explicit email invitation

Permissions:

• Can make changes: Read/write access (default)

• View only: Read-only access (future enhancement)

Invitation Method:

1. Copy Link: Copy share URL to clipboard

2. Messages: Send via iMessage

3. Email: Send via Mail app

4. AirDrop: Share to nearby devices

5. More: Any app that accepts URLs

Step 4: Send Invitation

Recommended Method: Messages or Email

Share URL Format:

https://www.icloud.com/share/[ShareID]#[Token]

Message Template:

Hi [Name],

You've been invited to collaborate on [Company Name] in TheCompanyApp.

Tap this link to accept:
[Share URL]

Make sure you have TheCompanyApp installed from TestFlight/App Store.

Step 5: Manage Participants

After sharing, the Share Settings screen shows:

Current Participants:

• List of all users who accepted

• Shows display name, email (from CKShare.Participant)

• Permission level (Can Edit / View Only)

Owner Actions:

• Remove Participant: Tap participant → Remove

• Change Permissions: Tap participant → Change to View Only

• Stop Sharing: Delete entire share (revokes all access)

Participant Status:

• Accepted: User has accepted and has access

• Pending: Invitation sent but not accepted yet

Accepting Invitation (Participant)

Step 1: Receive Invitation

Participants receive share link via:

• iMessage

• Email

• AirDrop

• Any messaging platform

Step 2: Open Share Link

On iOS Device:

1. Tap the share URL

2. Safari opens briefly

3. URL redirects to TheCompanyApp (universal link)

4. Or prompts to install app if not installed

Universal Link Format: The app handles URLs matching:

https://www.icloud.com/share/*

Step 3: Accept Share

TheCompanyApp opens and presents acceptance UI:

ContentView.swift detects incoming share:

.onOpenURL { url in
    if url.absoluteString.contains("icloud.com/share") {
        acceptIncomingShareAsync(from: url)
    }
}

Acceptance Flow:

func acceptIncomingShareAsync(from url: URL) async {
    do {
        // 1. Extract CKShareMetadata from URL
        let container = CKContainer(identifier: "iCloud.TheCompany.3N")
        let metadata = try await container.shareMetadata(for: url)
        
        // 2. Accept the share
        let acceptResult = try await container.accept(metadata)
        
        // 3. CloudKit adds share to Shared Database
        // 4. Core Data syncs company to Shared Store
        // 5. Company appears in companies list
        
        // Show success message
        print("✅ Share accepted successfully")
    } catch {
        // Show error
        print("❌ Failed to accept share: \(error)")
    }
}

Loading State: Progress indicator shown during accept operation (can take 5-30 seconds).

Step 4: Wait for Sync

After acceptance:

• CloudKit begins syncing company data to Shared Store

• Progress may take 10 seconds to 2 minutes depending on data size

• Pull down to refresh if company doesn't appear immediately

Step 5: Create UserPass

Company now appears in list:

1. Tap the new company

2. App detects missing UserPass

3. "Create Account" screen appears

4. Create your own username/password (see Create User Password)

5. Credentials saved to your Personal Private Store (not shared)

Step 6: Access Company Data

After creating UserPass:

• Full access to shared company

• See inventory, orders, contacts, etc.

• Changes sync in real-time to all participants

• Your UserPass remains local and private

Data Sharing Mechanics

What Gets Shared

When a company is shared, participants gain access to:

• ✅ Company details (name, logo, address)

• ✅ Inventory items

• ✅ Orders and invoices

• ✅ Dispatch records

• ✅ Tasks and assignments

• ✅ Contacts

• ✅ Warehouse configurations

• ✅ AccessControl records (for all participants)

• ✅ Audit logs

What Doesn't Get Shared

Private to each user:

• ❌ UserPass (username, password)

• ❌ Personal app settings

• ❌ Notification preferences

• ❌ Device-specific state

Sync Direction

Bi-Directional: All participants can:

• Create new records (add inventory, create orders)

• Update existing records (edit orders, adjust stock)

• Delete records (based on AccessControl permissions)

• Changes sync to all devices in real-time

Real-Time Sync

CloudKit Push Notifications:

• When Owner adds an order, participants' devices get notified

• When Participant updates inventory, owner sees change immediately

• Handled via .NSPersistentStoreRemoteChange notifications

Sync Timing:

• Usually instant (< 1 second on good network)

• Up to 30 seconds on slow networks

• Background sync continues even when app inactive

Permissions & Access Control

Share-Level Permissions

Set in UICloudSharingController:

• Can make changes: Full read/write (default for participants)

• View only: Read-only access (future enhancement)

App-Level Permissions

Managed via AccessControl entity:

Owner Advantages:

• isOwner = true in AccessControl

• Can manage sharing (add/remove participants)

• Can delete company

• Full access to all data

Participant Rights:

• isOwner = false in AccessControl

• Create and edit company data

• Cannot manage sharing settings

• Cannot delete company (can only leave)

Future Enhancement: Role-based permissions (Manager, Staff, Viewer) enforced via deptMask and managerMask.

Managing Shared Companies

Viewing Participants (Owner)

Settings → Sharing:

• See all current participants

• View participant email/name

• See when they joined (acceptedAt timestamp)

Removing Participants (Owner)

1. Settings → Sharing

2. Tap participant to remove

3. Tap "Remove"

4. Confirm removal

Effect:

• Participant loses access immediately

• Company removed from their device on next sync

• Their local data remains until they manually delete app data

Changing Permissions (Owner)

1. Select participant

2. Tap "Change Permission"

3. Choose new permission level

4. CloudKit updates share permissions

Note: Currently only binary (read/write vs. read-only). Future fine-grained control planned.

Leaving a Shared Company (Participant)

1. Select shared company

2. Settings → Sharing

3. Tap "Leave Company" or "Stop Sharing"

4. Confirm

Effect:

• Company removed from your device

• No longer receive updates

• Owner can re-invite if needed

Stopping All Sharing (Owner)

Deletes entire CKShare:

1. Settings → Sharing

2. Tap "Stop Sharing" (bottom of screen)

3. Confirm action

Effect:

• All participants lose access

• Company remains on owner's device (Private Store)

• Converts back to private company

• Can re-share later (creates new CKShare)

Troubleshooting Sharing

"Cannot Share on Free Tier"

Cause: Free tier doesn't support sharing.

Solution: Upgrade to Business or Enterprise tier in Settings.

"Failed to Create Share"

Cause: CloudKit error, network issue, or quota limit.

Solutions:

1. Check internet connection

2. Verify iCloud storage not full

3. Wait 30 seconds and retry

4. Check CloudKit dashboard for quota errors

Participant Can't Accept Invitation

Cause: Multiple possibilities.

Solutions:

1. Verify participant has TheCompanyApp installed

2. Ensure participant signed in to iCloud

3. Send share link again (previous may have expired)

4. Check participant's iCloud storage not full

Company Not Appearing After Accept

Cause: Sync delay.

Solutions:

1. Wait 1-2 minutes

2. Pull down to refresh companies list

3. Force quit and reopen app

4. Check internet connection

Participant Can't See New Data

Cause: Data not enlisted in share, or sync delay.

Solutions:

1. Owner: Verify data created after sharing is enlisted

2. Wait for CloudKit sync (up to 1 minute)

3. Pull down to refresh in affected tab

4. Check logs for "ensureEnlistedIfShared" calls

Changes Not Syncing

Cause: Network issue, merge conflict, or store mismatch.

Solutions:

1. Check internet connection on both devices

2. Force sync by pulling to refresh

3. Check Console logs for CloudKit errors

4. Verify both users have latest app version

Technical Deep Dive

CKShare Creation

File: ChoosVersionView.swift

func createCKShareIfNeeded() async {
    let company = selectedCompany
    
    // Check for existing share
    if let existingShare = try? container.fetchShares(matching: [company.objectID])[company.objectID] {
        presentShareController(with: existingShare)
        return
    }
    
    // Create new share
    let (_, share) = try await container.share([company], to: nil)
    
    // Enlist related objects
    let items = fetchInventoryItems(for: company.companyID)
    let orders = fetchOrders(for: company.companyID)
    let contacts = fetchContacts(for: company.companyID)
    // ... all company-scoped entities
    
    let allObjects = items + orders + contacts
    try await container.share(allObjects, to: share)
    
    presentShareController(with: share)
}

Share Root

Important: The Companies entity itself is the root of the CKShare:

// Companies is share root
share.rootRecord = companiesRecord

// All child entities reference Companies
childRecord[CKRecord.parent] = CKRecord.Reference(
    recordID: companiesRecord.recordID, 
    action: .none
)

This hierarchical structure ensures:

• All company data is part of the same share

• Deleting share removes all related data from participants

• Queries automatically scope to share zone

Enlistment Strategy

New records created after sharing must be enlisted:

context.insertCompanyItem(
    selectedCompanyIDString: selectedCompanyID,
    container: container,
    entity: InventoryItem.self,
    configure: { item, company in
        item.itemCode = "ITEM001"
        // ... configure item
    }
)

// Inside insertCompanyItem:
Task { @MainActor in
    await context.ensureEnlistedIfShared([newItem], under: company, using: container)
}

This automatically adds the new item to the CKShare if one exists.

---

Related: CloudKit Sharing Flow, Ownership Rules, Shared Store