# README

## Overview

The Chart of Accounts (CoA) Management module manages the master data for an organization's financial account structure. It provides a CoA container entity scoped per company (legal entity), GL accounts classified by standard accounting types (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) with operational classifications (REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, NON_POSTING), hierarchical account groups as structural metadata, and a lifecycle state machine (DRAFT → ACTIVE → ARCHIVED for the CoA container; DRAFT → ACTIVE ↔ INACTIVE for individual GL accounts) that controls when accounts can receive postings.

The CoA is the foundational accounting master data that all downstream financial modules reference. Journal entries in the general ledger post to accounts defined here; accounts payable and receivable reference GL control accounts identified by their operational classification; downstream modules consume the account group hierarchy for balance aggregation and reporting. The module owns the account definitions and structural hierarchy but does not own transactional posting, balance computation, or reporting aggregation — those responsibilities belong to separate general-ledger and reporting modules.

## Key Features

- **[Chart of Accounts Setup](docs/features/chart-of-accounts-setup.md)**: Creation and management of CoA containers scoped per company. Each CoA has a name, description, and lifecycle status (DRAFT → ACTIVE → ARCHIVED). The CoA inherits its base currency from the parent company (owned by the organization module). A company has one active CoA at a time, serving as the single authoritative account structure
- **[Account Management](docs/features/account-management.md)**: CRUD operations for GL accounts within a CoA. Each account carries a structured code, name, account type (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE), operational classification (REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, NON_POSTING), optional currency restriction, reconciliation flag, default tax code, and tags for cross-cutting categorization
- **[Account Group & Hierarchy](docs/features/account-group-hierarchy.md)**: Organization of accounts into named groups with hierarchical nesting. Groups define logical categories (e.g., "Current Assets", "Operating Expenses") and can control account numbering ranges. A single operational tree structure per CoA provides structural metadata that downstream modules consume for balance aggregation and reporting
- **[Account Lifecycle](docs/features/account-lifecycle.md)**: Status management for GL accounts through a state machine (DRAFT → ACTIVE ↔ INACTIVE). Controls when accounts can receive postings, includes successor account mapping for deprecated accounts, and exposes a pre-deactivation hook for balance verification by the general-ledger module

## Module Scope

### In Scope

- Chart of Accounts container management (create, update, archive) scoped per company
- GL account master data management (create, update, deactivate) with structured account codes
- Account type classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) with operational classifications (REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, NON_POSTING)
- Account group management with hierarchical nesting as structural metadata for downstream consumption
- Account lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) with pre-deactivation hook for external balance checks
- Successor account mapping for deprecated accounts
- Account currency restriction (optional per-account currency assignment, referencing primitives module)
- Reconciliation flag for bank, receivable, and payable accounts
- Tag-based categorization for cross-cutting account filtering

### Out of Scope

- Journal entries and posting rules (general-ledger module)
- Trial balance and balance aggregation (general-ledger module)
- Fiscal calendar — fiscal years, periods, cutoff dates (accounting module)
- Cost centers and profit centers (management-accounting module)
- Business units and divisions for financial reporting (management-accounting module)
- Multi-segment account structures — Oracle-style Key Accounting Flexfield (future enhancement)
- Cross-validation rules for segment combinations (future enhancement)
- Fiscal localization packages — country-specific CoA templates (application layer)
- Multi-book accounting — parallel books under different GAAP (general-ledger module)
- Consolidation mapping — subsidiary to group CoA mapping (consolidation module)
- Financial statement version management (reporting module)
- Bulk import/export of accounts (application-layer tooling)

### Scope Decision Rationale

CoA Management is scoped to **accounting master data** — the "what accounts exist and how they are structured" foundation. It owns the account definitions, type classification, grouping hierarchy, and lifecycle but does not own transactional concerns like journal entries, balance computation, or period-end close. This separation follows the standard ERP pattern where the Chart of Accounts is a reference data module consumed by transactional modules (general-ledger, AP, AR, fixed-assets).

Fiscal calendar is excluded because it is a shared accounting concern needed by multiple modules (general-ledger, AP, AR, budgeting) and should not be owned by the account structure module. Fiscal calendar ownership belongs to the accounting module, consistent with the organization module's deferral. Similarly, cost centers and profit centers are management-accounting dimensions that cross-cut many modules — the organization module explicitly defers these to a future accounting module, and they are better served by a dedicated management-accounting module.

Multi-segment account structures (Oracle's Key Accounting Flexfield pattern) are deferred as a future enhancement. The initial design uses a single structured account code, which covers the majority of use cases. Segment-based design can be layered on later without breaking the core account model.

Country-specific CoA templates (fiscal localizations) are excluded because they are data packages rather than domain logic. They belong in the application layer where they can be installed as configuration, not in the core module.

## Module Dependencies

- [organization](../organization/README.md) — Company reference for CoA and account scoping (each CoA belongs to a company); base currency is inherited from the company
- [primitives](../primitives/README.md) — Currency definitions for per-account currency restriction
- [audit](../audit/README.md) — Audit trail for account master data changes (account creation, modification, status transitions)
- **general-ledger** (future integration) — Reads successor account mappings to redirect postings; provides balance-check hook to block account deactivation when open balances exist; determines whether an account has posted transactions
- **tax-configuration** (future integration) — Will own the tax code catalog and validate default tax code references stored on accounts. Migration contract: when `tax-configuration` is implemented, this module will add a dependency and enforce referential integrity on the `defaultTaxCode` field. Until then, tax codes are stored as free-text identifiers with no external validation
