Company Switching

Guide to managing and switching between multiple companies in TheCompanyApp.

Overview

TheCompanyApp's multi-tenancy architecture allows a single user to:

• Own multiple companies simultaneously

• Participate in companies owned by others

• Switch between companies instantly

• Maintain separate context for each company

Each company is completely isolated — orders, inventory, contacts, and all data are scoped to the selected company.

Why Multiple Companies?

Common Use Cases

Consultants & Freelancers

• Manage separate companies for different clients

• Keep project data isolated

• Switch context quickly during meetings

Franchise Owners

• Operate multiple franchise locations as separate companies

• Use same app for all locations

• Corporate can share a master company with all franchisees

Multi-Business Owners

• Run different businesses (e.g., retail + wholesale)

• Separate accounting and inventory

• Independent team members per business

Employee of Multiple Organizations

• Participate in employer's company

• Own a side business

• Help friend's startup

• All accessible from one app

Understanding Company Types

When you view your companies list, each falls into one of two categories:

Owned Companies (Private Store)

Characteristics:

• You created this company

• You are the owner (isOwner = true in AccessControl)

• Data stored in Private Store (TheCompanyApp.sqlite)

• Syncs to iCloud Private Database

• Only on your devices unless you share it

• Can invite team members (Business/Enterprise tier)

• Full control over all settings

Indicator in UI: "Owner" badge or icon

Shared Companies (Shared Store)

Characteristics:

• Created and shared by someone else

• You accepted a share invitation

• Data stored in Shared Store (TheCompanyApp-shared.sqlite)

• Syncs to iCloud Shared Database

• Visible to all participants

• Limited control (based on AccessControl permissions)

• Cannot delete company (only leave share)

Indicator in UI: "Participant" badge or shared icon

Company List View

Accessing the List

From Dashboard:

1. Tap company name in navigation bar

2. Company selector sheet appears

From Settings:

1. Navigate to Settings tab

2. Tap "Switch Company" or "Companies"

Company List UI

Each company row displays:

• Company Logo (if set)

• Company Name

• Owner Badge (if you own it)

• Tier (Free, Business, Enterprise)

• Last Selected indicator (checkmark or highlight)

Sort Order:

• Last accessed companies first (by timestamp)

• Then alphabetically by name

Search:

• Search bar to filter companies by name

• Real-time filtering as you type

Switching Companies

Quick Switch

To switch to a different company:

1. Tap Company Selector (company name at top)

2. Tap Company you want to switch to

3. Sheet dismisses, app immediately loads new company context

What Happens Internally:

@AppStorage("selectedCompanyID") var selectedCompanyIDString: String = ""

// When tapped:
selectedCompanyIDString = newCompany.companyID.uuidString

// All views auto-update:
@FetchRequest(
    sortDescriptors: [...],
    predicate: NSPredicate(format: "companyID == %@", selectedCompanyID)
)
var orders: FetchedResults<Orders>

Effects:

• All tabs reload with new company's data

• Dashboard shows new company's metrics

• Inventory shows new company's items

• Orders show new company's orders

• Contacts show new company's contacts

Persistence:

• New selection saved to AppStorage

• Remembered across app launches

• Each device tracks its own selection independently

Switching from Login Screen

If you're at login screen and want to choose a different company:

1. Tap "< Back" or "Companies" button

2. Returns to companies list

3. Tap different company

4. New login screen appears for that company

Company Context

What Changes When Switching

Data Scope:

• All fetch requests filter by new companyID

• Previous company's data instantly hidden

• New company's data loads from Core Data

User Context:

• UserPass for new company loaded (separate credentials)

• AccessControl for new company applied

• Permissions and roles switch

CloudKit Store:

• Owned company → reads from Private Store

• Shared company → reads from Shared Store

• App handles store resolution automatically

UI State:

• Resets to default tab (Dashboard)

• Clears any unsaved forms

• Refreshes all list views

What Doesn't Change

App Settings:

• Notification preferences (global)

• UI theme/appearance

• App-level configurations

iCloud Account:

• Same Apple ID

• Same CloudKit container

Device State:

• Background sync continues for all companies

• Notifications can arrive for any company

Managing Multiple Companies

Creating Additional Companies

You can create unlimited companies:

1. From Companies List:

   • Tap + "Create Company" button

   • Follow creation flow (see Create First Company)

2. Company Creation:

   • Each company gets unique companyID

   • Separate data scope

   • Independent tier/subscription

   • Own UserPass credentials

Joining Additional Companies

Accept invitations from others:

1. Receive Share Link (via Messages, Email, etc.)

2. Open Link (opens TheCompanyApp)

3. Accept Share (see Sharing Company)

4. Company Appears in companies list

5. Create UserPass when accessing first time

Deleting a Company

For Owned Companies:

1. Select the company

2. Navigate to Settings → Company Info

3. Scroll to bottom

4. Tap "Delete Company" (red text)

5. Confirm deletion (irreversible)

Effect:

• All company data deleted locally

• CloudKit records deleted from Private Database

• If shared, participants lose access too

• Cannot be undone

For Shared Companies (Participant):

1. Select the company

2. Navigate to Settings → Sharing

3. Tap "Leave Company"

4. Confirm

Effect:

• Company removed from your device

• Your access revoked

• Owner can re-invite if needed

Performance Considerations

Switching Speed

Company switching is designed to be instant:

Optimization 1: No Network Calls

• All data already synced locally

• Switch happens purely in Core Data

• No API calls or waiting

Optimization 2: Lazy Loading

• Data fetched only when tab is viewed

• @FetchRequest updates automatically

• No manual refresh needed

Optimization 3: In-Memory Store Reference

func resolveCompanyAndStore(selectedCompanyIDString: String) -> (Companies, NSPersistentStore)? {
    // Returns both company and its persistent store
    // Views use correct store automatically
}

Memory Management

With many companies:

• Only selected company's data active in memory

• Background syncing lightweight (handles all companies)

• No performance degradation with 10, 50, or 100 companies

Company Isolation

Data Isolation Guarantees

TheCompanyApp ensures absolute data isolation:

Query-Level Filtering:

// Every query includes company predicate
predicate = NSPredicate(format: "companyID == %@", selectedCompanyID)

No Cross-Company Queries:

• Cannot accidentally fetch data from Company A while viewing Company B

• Inventory, orders, contacts always scoped

• Reports and analytics respect company boundary

Accidental Leakage Prevention:

• insertCompanyItem() helper assigns objects to correct store

• Company-scoped views enforce companyID filter

• Relationships validated against company

Syncing Across Devices

How Companies Sync

Owned Companies:

1. Created on Device A

2. Saved to Private Store

3. CloudKit syncs to Private Database

4. Device B (same Apple ID) pulls from Private Database

5. Appears in companies list on Device B

Shared Companies:

1. Owner shares company

2. Participant accepts on Device A

3. Saved to Shared Store

4. CloudKit syncs to Shared Database

5. Device B (participant's devices) pulls from Shared Database

6. Appears in companies list on Device B

Sync Timing:

• Usually instant to 1 minute

• Background sync continues even when inactive

• Pull to refresh forces immediate check

Edge Cases

Same Company in Both Stores

Scenario: You own Company X, then someone else re-shares the same company name to you.

Reality: Different companies despite same name.

• Each company has unique companyID

• Two separate entities in your list

• No conflict

Best Practice: Use unique company names to avoid confusion.

Owner Also Participant

Scenario: You own Company A, then accept a share for Company A from another device.

Current Behavior: Undefined (likely creates duplicate).

Recommendation: Don't share a company to yourself. Use single-owner model.

Switching While Saving

Scenario: Editing an order in Company A, switch to Company B before saving.

Result: Changes lost (not saved).

Mitigation: App should warn about unsaved changes (planned enhancement).

Troubleshooting

Company Not Appearing

Cause: Sync delay or sharing failure.

Solution:

1. Pull down to refresh companies list

2. Wait 1-2 minutes for sync

3. Check iCloud connection

4. Verify share was accepted correctly

Wrong Data Showing After Switch

Cause: Cached data or fetch request not updating.

Solution:

1. Pull down to refresh in affected tab

2. Force quit and restart app

3. Check that @FetchRequest includes companyID predicate

Cannot Delete Company

Cause: Shared company (you're participant).

Solution:

• Use "Leave Company" instead of "Delete"

• Contact owner to transfer ownership first (if needed)

Lost Company After Update

Cause: CloudKit sync issue or data corruption.

Solution:

1. Check iCloud storage hasn't exceeded quota

2. Sign out and back in to iCloud

3. Reinstall app (data should restore from iCloud)

Technical Reference

Company Fetching

@FetchRequest(
    sortDescriptors: [NSSortDescriptor(keyPath: \Companies.timestamp, ascending: false)],
    animation: .default
)
var allCompanies: FetchedResults<Companies>

Company Classification

func classifyCompanies() {
    let ownedCompanies = allCompanies.filter { company in
        // From private store
        company.objectID.persistentStore != sharedStore()
    }
    
    let sharedCompanies = allCompanies.filter { company in
        // From shared store
        company.objectID.persistentStore == sharedStore()
    }
}

Switching Logic

func switchCompany(to company: Companies) {
    // Update AppStorage
    selectedCompanyIDString = company.companyID!.uuidString
    
    // Triggers SwiftUI view updates
    // All @FetchRequest predicates re-evaluate
}

---

Next: Sharing Company Related: Company Scoping, Private Store, Shared Store