# Documentation Home

Welcome to the complete technical documentation for **TheCompanyApp** — a comprehensive iOS business management platform built with SwiftUI, Core Data, and CloudKit.

## What is TheCompanyApp?

TheCompanyApp is a full-featured business operations platform designed for iOS and iPadOS. It enables companies to manage inventory, process orders, coordinate dispatch operations, maintain contacts, track warehouse logistics, and collaborate in real-time with team members across multiple Apple devices.

The app is built on a sophisticated multi-tenant architecture with CloudKit-backed company sharing, enabling secure real-time collaboration while maintaining strict data isolation between different companies.

## Who This Documentation Is For

This documentation serves three primary audiences:

### Product Teams & Stakeholders

Learn about the product vision, features, and roadmap to understand what TheCompanyApp delivers to users.

### End Users

Complete guides for using the app, from creating your first company to advanced workflows like multi-user dispatch coordination.

### Developers & Architects

Technical reference for the Core Data model, CloudKit synchronization architecture, company-scoped persistence strategies, and remote change handling.

## Documentation Structure

The documentation is organized into logical sections:

### 📘 Product Documentation

* **Overview**: Product vision and value proposition
* **Core Concepts**: Multi-tenancy, company scoping, and sync model
* **Feature Map**: Complete catalog of functionality
* **Roadmap**: Upcoming features and improvements

### 🚀 Getting Started

* **Installation**: System requirements and setup
* **Create First Company**: Complete onboarding flow
* **Login Flow**: Authentication and company selection
* **Company Switching**: Managing multiple companies
* **Sharing Companies**: Inviting team members

### 📖 User Guide

* **Dashboard**: Overview and quick actions
* **Inventory**: Stock management and tracking
* **Orders**: Sales order processing
* **Dispatch**: Logistics and delivery coordination
* **Tasks**: Assignment and tracking
* **Contacts**: Customer and supplier management
* **Access Control**: User permissions and roles
* **Notifications**: Alert configuration

### 🏗️ Architecture

* **System Overview**: High-level architecture
* **Core Data Model**: Entity relationships and attributes
* **Company Scoping**: Multi-tenant isolation strategy
* **Fetch Strategies**: Efficient data retrieval
* **Remote Change Handling**: CloudKit notification processing

### ☁️ CloudKit

* **Sync Architecture**: Private and shared database model
* **Private Store**: User-specific data synchronization
* **Shared Store**: Cross-user company data sharing
* **Sharing Flow**: CKShare creation and participation
* **Ownership Rules**: Owner vs participant permissions
* **Conflict Resolution**: Merge policies and strategies
* **Sync States**: Understanding CloudKit sync lifecycle
* **Troubleshooting**: Common issues and debugging

### 🔐 Security

* **Security Model**: Data isolation and protection
* **Credential Storage**: UserPass private database strategy
* **Data Isolation**: Company-scoped queries and persistence
* **Permissions and Roles**: AccessControl relationship model

### 🧪 Testing

* **TestFlight Flow**: Distributing and testing
* **Share Testing Checklist**: Validating multi-user scenarios
* **Debugging Logs**: Reading CloudKit logs
* **Common Issues**: Known problems and solutions

## Quick Navigation

| I want to...                     | Go to...                                                                                                            |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Understand what the app does     | [Product Overview](https://docs.3nsofts.com/product/overview)                                                       |
| Create my first company          | [Create First Company](https://docs.3nsofts.com/getting-started/create-first-company)                               |
| Invite team members              | [Sharing Company](https://docs.3nsofts.com/getting-started/sharing-company)                                         |
| Understand the data model        | [Core Data Model](https://github.com/EhsanAzish80/TheCompanyApp-IOS/blob/main/docs/architecture/core-data-model.md) |
| Learn how CloudKit sharing works | [Sharing Flow](https://docs.3nsofts.com/cloudkit/sharing-flow)                                                      |
| Debug sync issues                | [Troubleshooting](https://docs.3nsofts.com/cloudkit/troubleshooting)                                                |
| Understand security design       | [Security Model](https://docs.3nsofts.com/security/security-model)                                                  |

## Key Architectural Concepts

Before diving into the documentation, understand these core concepts:

### Company-Scoped Multi-Tenancy

Every data entity (except `UserPass` and `AccessControl`) is scoped to a specific company via `companyID`. This enables a single user to participate in multiple companies while maintaining complete data isolation.

### Dual Persistent Store Architecture

The app uses two Core Data persistent stores:

* **Private Store** (`TheCompanyApp.sqlite`): Syncs to iCloud Private Database (user's own data)
* **Shared Store** (`TheCompanyApp-shared.sqlite`): Syncs to iCloud Shared Database (invited company data)

### CloudKit Sharing Model

When a company owner shares their company:

1. The `Companies` record becomes the root of a `CKShare`
2. All related records are enlisted into the share's zone
3. Participants access the company via the Shared Store
4. Owners continue to access via Private Store

### Credential Isolation

`UserPass` entities (username/password) are stored **only** in the Private Store and never shared. Each participant maintains their own credentials locally, isolated from other users.

## Contributing to Documentation

This documentation reflects the actual implementation as of February 2026. When making changes to the app, update the corresponding documentation sections to maintain accuracy.

## Support & Feedback

For technical questions or clarifications about the implementation, review:

* The inline code comments in Swift files
* CloudKit logs using `OSLog` filtering
* Xcode's Core Data debugging tools

***

**Last Updated**: February 2026\
**App Version**: Compatible with iOS 16.0+\
**CloudKit Container**: `iCloud.TheCompany.3N`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.3nsofts.com/introduction/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.