# Company Lifecycle

## Overview

Companies are the root organizational entity in the Organization module. A company represents a legal entity — identified by its legal name, tax identification number, and registration number, along with its registered address and base currency assignment. Companies serve as the scoping entity for all transactional modules; every accounting entry, sales order, purchase order, and inventory movement belongs to exactly one company. Each company has a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that controls when transactional operations and downstream module integrations are permitted. Fiscal calendar management (fiscal year, periods, cutoff dates) is owned by the financial-accounting module — organization only provides the structural identity that financial-accounting attaches fiscal configuration to.

## Business Purpose

Companies model real-world legal entities that enter contracts, hold tax identities, and prepare financial statements. This enables:

- Multi-company support with data isolation: each transactional record is scoped by companyId
- Separation of legal entity setup from day-to-day operations — companies are fully configured before going live
- Assignment of a base/functional currency per company (referencing the primitives module's Currency), ensuring consistent monetary calculations. Currency master data (ISO codes, symbols, exchange rates) is owned by the primitives module; organization only stores which currency a company uses as its base currency

The lifecycle ensures:

- Companies are reviewed and fully configured before downstream modules can reference them (DRAFT → ACTIVE). Activation means the structural identity (legal name, tax ID, registered address, base currency) is complete — it does not imply transactional readiness. Downstream master-data modules (e.g., CoA management) and transactional modules each enforce their own readiness gates on top of company ACTIVE status
- Inactive companies stop accepting new transactions while preserving all historical data
- Only DRAFT companies can be permanently deleted; ACTIVE/INACTIVE companies are preserved for audit and legal compliance

## Process Flow

```mermaid
stateDiagram-v2
    [*] --> Draft: createCompany
    Draft --> Active: activateCompany
    Active --> Inactive: deactivateCompany
    Inactive --> Active: reactivateCompany
    Draft --> [*]: deleteCompany
```

The company creation and setup flow follows this pattern:

```mermaid
flowchart TD
    A[Create Company] --> B[Set Legal Details]
    B --> C[Configure Registered Address]
    C --> D[Assign Base Currency]
    D --> E{Ready to go live?}
    E -->|Yes| F[Activate Company]
    E -->|No| G[Continue editing]
    G --> B
    F --> H[Available for Transactions]
```

## Scenario Patterns

- **New Company Setup**: A company is created in DRAFT with its legal name and tax identification number. The registered address and base currency are configured, then the company is activated to confirm its structural identity is complete. After activation, master-data modules (e.g., CoA management) can begin building financial configuration on top of the company. Transactional readiness (e.g., journal posting) requires additional setup: an active Chart of Accounts and fiscal calendar configuration
- **Company Deactivation**: A legal entity ceases operations. The company moves to INACTIVE status, preventing new transactions from being created against it, but all historical records remain accessible for reporting and audit
- **Company Reactivation**: A previously inactive company resumes operations and is reactivated, allowing new transactions to be recorded against it
- **Draft Cleanup**: Incomplete company records in DRAFT are deleted before activation when a planned legal entity is no longer needed
- **Multi-Company Expansion**: A new subsidiary is added to the system as a separate company with its own base currency, enabling consolidated reporting across legal entities. Fiscal calendar for the subsidiary is configured independently via the financial-accounting module

## Test Cases

- Company lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
- Companies can only be created in DRAFT status
- Only DRAFT companies can be deleted; ACTIVE and INACTIVE companies cannot
- Legal name is required and must be non-empty
- Tax identification number is stored and queryable per company
- Registration number is stored per company
- Base currency is optional at creation but must be set and reference a valid Currency from the primitives module before activation
- Base currency is immutable after activation to preserve transactional consistency
- Registered address fields are required before activation
- Activating a company without required fields (legal name, base currency, registered address) is rejected
- Deactivating a company does not affect existing historical transactions
- Reactivating an INACTIVE company returns it to ACTIVE status
- Each company has a unique companyId used for data isolation across transactional modules
- Deleting an ACTIVE or INACTIVE company returns an error

## Reference Links

- [SAP Business One Company Setup](https://help.sap.com/docs/SAP_BUSINESS_ONE)
- [Odoo Multi-Company](https://www.odoo.com/documentation/19.0/applications/general/companies.html)
- [Dynamics 365 Legal Entities](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/organization-administration/plan-organizational-hierarchy)
- [Oracle Financials Legal Entity Configuration](https://docs.oracle.com/en/cloud/saas/financials/24d/faigl/legal-entities.html)