# Chart of Accounts Setup

## Overview

The Chart of Accounts (CoA) is the top-level container that organizes all GL accounts, account groups, and hierarchies for a company. Each CoA is scoped to a single legal entity (via `companyId` from the organization module), carries a name, description, and a lifecycle status. The CoA inherits its base currency from the parent company's base currency assignment (owned by the organization module), ensuring a single source of truth for monetary scope. A company may define multiple CoA records over time, but only one can be active at any point, ensuring a single authoritative account structure drives all downstream posting.

CoA setup is the first step in configuring a company's financial master data. The process typically starts from a country-specific template or a blank structure, proceeds through creating account groups (which define the allowed account numbering ranges), populating GL accounts, and concludes with activation. Once active, the CoA becomes the reference frame for account management, account group hierarchy, and ultimately for journal entries in the general-ledger module.

## Business Purpose

Organizations need a well-defined account container to maintain consistent financial reporting and regulatory compliance:

- **Single authoritative structure**: One active CoA per company prevents conflicting account definitions and ensures all ledger postings reference a unified structure
- **Company scoping**: Each CoA is isolated to a legal entity, supporting multi-entity and multi-country deployments with distinct regulatory requirements
- **Template-driven setup**: Starting from a localized template (similar to Odoo's 50+ country packages or SAP's country-specific CoA) accelerates initial configuration and reduces errors. Templates are externally managed configuration data — each template is an immutable, pre-defined snapshot containing a set of account groups (with numbering ranges) and GL accounts for a specific country or industry. This module treats templates as an **external dependency**: template storage, versioning, and catalog management are outside the scope of coa-management. The `createChartOfAccounts` command accepts an optional `templateId` and delegates template resolution to the template provider. If no template provider is configured, only blank CoA creation is available
- **Base currency inheritance**: The CoA inherits its base currency from the parent company (organization module), establishing a consistent reporting currency for all accounts without duplicating currency ownership
- **Company status dependency**: A CoA can only be created for a company that is in ACTIVE status (as defined by the organization module's company lifecycle). Company ACTIVE status confirms the structural identity (legal name, tax ID, registered address, base currency) is complete — it is a prerequisite for financial master data setup, not a guarantee of transactional readiness
- **Layered readiness model**: Company ACTIVE status is the first gate (structural identity). CoA ACTIVE status is the second gate (accounting readiness). Transactional modules (e.g., general-ledger) require both an ACTIVE company and an ACTIVE CoA before journal postings are permitted. This layered model means a company can be ACTIVE while its accounting structure is still being configured in a DRAFT CoA
- **Lifecycle gating**: The CoA lifecycle (DRAFT → ACTIVE → ARCHIVED) controls when GL accounts can be created and modified. Accounts can be added to a CoA in both DRAFT and ACTIVE status, but only accounts under an ACTIVE CoA can receive journal postings from downstream modules
- **Audit preservation**: Deprecated CoA records are archived rather than deleted, retaining the historical account structure for audit and restatement purposes

## Process Flow

```mermaid
stateDiagram-v2
    [*] --> Draft: createChartOfAccounts
    Draft --> Active: activateChartOfAccounts
    Active --> Archived: deactivateChartOfAccounts
    Draft --> [*]: deleteChartOfAccounts
```

```mermaid
flowchart TD
    A[Select template or start blank] --> B[Create CoA in DRAFT]
    B --> C[Create account groups with numbering ranges]
    C --> D[Add GL accounts]
    D --> E{Validation passed?}
    E -- Yes --> F[Activate CoA]
    E -- No --> C
    F --> G[CoA ready for postings]
```

## Scenario Patterns

- **Greenfield Company Setup**: A newly incorporated entity creates a CoA from a country-localized template, configures account groups (with their numbering ranges), adds required GL accounts, and activates the CoA before the first fiscal period opens
- **Blank CoA for Holding Company**: A holding company with non-standard reporting requirements creates a blank CoA, manually defines a minimal account structure tailored to consolidation needs, and activates it
- **Multi-Entity Rollout**: A parent organization sets up separate CoA records for each subsidiary, each scoped to its own company and base currency, reflecting local GAAP requirements
- **CoA Replacement**: A company undergoing a regulatory change creates a new CoA in DRAFT alongside the currently active one, migrates account mappings, then archives the old CoA and activates the new one
- **Draft Cleanup**: An incorrectly configured CoA still in DRAFT is deleted along with all child Account and AccountGroup records via cascade deletion. Because only DRAFT CoAs can be deleted, all child accounts are guaranteed to be in DRAFT status with no posted transactions, making the cascade safe. Each cascade-deleted child emits its own audit event before the CoA deletion event
- **Currency Inheritance**: When a CoA is created for a company, it inherits the company's base currency (set via the organization module). All accounts within the CoA use this inherited currency as the default reporting currency

## Test Cases

- CoA lifecycle follows DRAFT -> ACTIVE -> ARCHIVED state machine
- CoA can only be created in DRAFT status
- CoA name is required and must be non-empty
- CoA must reference a valid companyId from the organization module
- The referenced company must be in ACTIVE status; creating a CoA for a DRAFT or INACTIVE company is rejected
- CoA inherits its base currency from the parent company's base currency (organization module)
- The parent company must have a base currency assigned before a CoA can be created (guaranteed by the ACTIVE status requirement, since company activation requires base currency)
- Only one CoA per company can be in ACTIVE status at a time
- Activating a DRAFT CoA transitions status to ACTIVE
- Activating an already ACTIVE CoA fails with an invalid status transition error
- Archiving an ACTIVE CoA transitions status to ARCHIVED
- Archiving a DRAFT CoA fails with an invalid status transition error
- Reactivating an ARCHIVED CoA is not permitted
- Only DRAFT CoA records can be deleted; ACTIVE and ARCHIVED records cannot
- Deleting a DRAFT CoA cascade-deletes all child Account and AccountGroup records belonging to it; all children are guaranteed to be in DRAFT status with no posted transactions since account activation requires an ACTIVE CoA
- Each cascade-deleted child record (Account and AccountGroup) emits its own audit event, followed by the CoA deletion audit event
- GL accounts can be created under a CoA in DRAFT or ACTIVE status
- GL accounts under an ACTIVE CoA can receive journal postings from downstream modules
- CoA records are scoped to a company; CoA records from different companies are isolated
- Creating a second ACTIVE CoA for the same company fails with a uniqueness constraint error
- CoA description is optional and can be updated while in DRAFT or ACTIVE status
- Creating a CoA emits an audit event via the audit module recording the acting user, timestamp, and initial field values
- Updating a CoA (name, description) emits an audit event recording the previous and new field values
- Activating a CoA emits an audit event recording the status transition from DRAFT to ACTIVE
- Archiving a CoA emits an audit event recording the status transition from ACTIVE to ARCHIVED
- Deleting a DRAFT CoA emits an audit event recording the deletion and acting user

## Reference Links

- [SAP Chart of Accounts Configuration](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/5c20e46f4ce446a592e69e26ee3c0b37.html)
- [Oracle Fusion Chart of Accounts Structure](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/chart-of-accounts.html)
- [Odoo Chart of Accounts and Localization](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/chart_of_accounts.html)
- [NetSuite Chart of Accounts Overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N671498.html)
