@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/coa-management/docs/features/chart-of-accounts-setup.md

@@ -0,0 +1,86 @@
+# 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)

package/src/modules/coa-management/docs/models/Account.md

@@ -0,0 +1,84 @@
+# Account
+
+## Description
+
+Account is the fundamental GL account entity in the ERP system — every journal entry, sub-ledger posting, and financial report ultimately references one or more GL accounts. Each account carries a structured numeric code, a descriptive name, an account type (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE), an account classification describing its operational role (REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, NON_POSTING), optional currency restriction, reconciliation flag, default tax code reference, and tags.
+
+Accounts are always scoped to a parent CoA and may optionally belong to an account group. The account follows a lifecycle state machine (DRAFT -> ACTIVE <-> INACTIVE) that governs posting eligibility, mutability, and deletion.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAccount
+    Draft --> Active: activateAccount
+    Active --> Inactive: deactivateAccount
+    Inactive --> Active: reactivateAccount
+    Draft --> [*]: deleteAccount
+```
+
+### Command Definitions
+
+- [createAccount](../commands/CreateAccount.md) - Create a new GL account in DRAFT status within a CoA
+- [updateAccount](../commands/UpdateAccount.md) - Update mutable fields of an existing account (structural fields immutable after posting)
+- [activateAccount](../commands/ActivateAccount.md) - Transition account from DRAFT to ACTIVE
+- [deactivateAccount](../commands/DeactivateAccount.md) - Transition account from ACTIVE to INACTIVE with optional successor mapping
+- [reactivateAccount](../commands/ReactivateAccount.md) - Transition account from INACTIVE to ACTIVE
+- [deleteAccount](../commands/DeleteAccount.md) - Permanently delete a DRAFT account with no posted transactions
+
+### Query Definitions
+
+- [GetAccount](../queries/GetAccount.md) - Retrieve an account by id or by code within a CoA
+- [ListAccounts](../queries/ListAccounts.md) - List accounts within a CoA with optional filters (type, classification, group, tags, status)
+
+### Models
+
+- Account
+
+### Invariants
+
+- Accounts can only be created in DRAFT status
+- Account creation and update require the parent CoA to be in DRAFT or ACTIVE status; operations on accounts under an ARCHIVED CoA are rejected
+- Account deactivation and reactivation require the parent CoA to be in ACTIVE status; the DRAFT CoA case is unreachable because these operations act on ACTIVE or INACTIVE accounts, which can only exist under an ACTIVE CoA (since account activation requires an ACTIVE CoA). Operations on accounts under an ARCHIVED CoA are rejected
+- Account deletion requires the parent CoA to be in DRAFT or ACTIVE status; operations on accounts under an ARCHIVED CoA are rejected
+- Account activation (activateAccount) specifically requires the parent CoA to be in ACTIVE status — not DRAFT. This ensures that all accounts under a DRAFT CoA remain in DRAFT status, which is a prerequisite for safe cascade deletion of DRAFT CoAs
+- Account code is required, must be a structured numeric identifier, and must be unique within its CoA
+- Account code is immutable after the account has posted transactions
+- Account name is required and must be non-empty
+- Account type must be one of ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE
+- Account classification must be one of REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, or NON_POSTING
+- Account classification defaults to REGULAR when not explicitly set
+- Classification must be compatible with account type: RECEIVABLE, BANK_CASH, and FIXED_ASSET require type ASSET; PAYABLE requires type LIABILITY; RETAINED_EARNINGS requires type EQUITY; REGULAR and NON_POSTING are allowed with any type
+- Only one account per CoA may carry the RETAINED_EARNINGS classification
+- Reconciliation flag defaults to false for REGULAR, FIXED_ASSET, RETAINED_EARNINGS, and NON_POSTING classifications
+- Accounts with RECEIVABLE, PAYABLE, or BANK_CASH classification must have reconciliation enabled (enforced invariant, not a default); attempting to set reconciliation to false for these classifications is rejected
+- RECEIVABLE and PAYABLE accounts block direct manual journal postings (control account constraint stored here, enforced by GL/posting layer)
+- NON_POSTING accounts are excluded from journal entry target selection (postability attribute only, not a hierarchy mechanism)
+- Currency restriction, when provided, must reference a valid currency from the primitives module
+- An account with currency restriction only accepts postings in that currency
+- Once an account has posted transactions, structural fields (code, type, classification, currency restriction) become immutable
+- Only ACTIVE accounts can receive new journal postings
+- Only DRAFT accounts with no posted transactions can be deleted; ACTIVE and INACTIVE accounts cannot be deleted regardless of transaction history
+- Deleting a DRAFT account that has posted transactions is rejected to preserve ledger integrity
+- Default tax code is optional free-text (future migration to validated reference when tax-configuration module is implemented)
+- Tags are optional; when provided, stored as a comma-separated string of labels (e.g. `"tag1,tag2"`)
+- An account can optionally belong to an account group within the same CoA; assigning an account to a group in a different CoA fails validation
+- When an account belongs to a group with a defined number range, the account code must always fall within that range — this invariant is enforced on creation, on group reassignment, and on code changes while the account remains in the same group
+- Deactivation exposes a pre-deactivation hook for the general-ledger module to block the transition when open or unreconciled balances exist
+- A successor account can optionally be mapped during deactivation; the successor must be in ACTIVE status
+- Reactivating an account clears any previously mapped successor account
+- All account lifecycle operations (create, update, activate, deactivate, reactivate, delete) emit audit events via the audit module recording the acting user, timestamp, CoA reference, account code, classification, and relevant field values
+
+### Relationships
+
+- **References ChartOfAccounts**: Each account belongs to a ChartOfAccounts via chartOfAccountsId
+- **References AccountGroup**: Each account optionally references an AccountGroup via accountGroupId
+- **References Currency**: Each account optionally references a Currency from the primitives module via currencyRestriction
+- **References Account (successor)**: Each account optionally references another Account as successor via successorAccountId
+- **Referenced By Downstream Modules**: Accounts are referenced by general-ledger, AP, AR, and fixed-asset modules

package/src/modules/coa-management/docs/models/AccountGroup.md

@@ -0,0 +1,55 @@
+# AccountGroup
+
+## Description
+
+AccountGroup organizes GL accounts into logical categories and nestable hierarchical tree structures within a Chart of Accounts. Each group has a code, name, optional parent group reference for nesting, a sort order that controls display sequencing, and an optional account number range that constrains which account codes can be assigned to the group's members.
+
+Groups can be nested to form a multi-level tree hierarchy. A root group with no parent represents a top-level section (e.g., "Assets"), while child groups subdivide it into progressively finer categories. The hierarchy defines structural metadata for the CoA; how that structure is consumed for balance aggregation or financial statement rendering is the responsibility of downstream modules.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createAccountGroup](../commands/CreateAccountGroup.md) - Create a new root or child account group within a CoA
+- [updateAccountGroup](../commands/UpdateAccountGroup.md) - Update the name, sort order, or number range of an existing group
+- [moveAccountGroup](../commands/MoveAccountGroup.md) - Reparent a group within the same CoA hierarchy
+- [deleteAccountGroup](../commands/DeleteAccountGroup.md) - Delete a group with no children or assigned accounts
+
+### Query Definitions
+
+- [GetAccountGroup](../queries/GetAccountGroup.md) - Retrieve an account group by id or code within a CoA
+- [ListAccountGroups](../queries/ListAccountGroups.md) - List account groups within a CoA, optionally filtered by parent
+- [ListUnassignedAccounts](../queries/ListUnassignedAccounts.md) - List active accounts within a CoA that are not assigned to any group
+- [DetectCircularReference](../queries/DetectCircularReference.md) - Validate that reparenting a group would not create a cycle
+
+### Models
+
+- AccountGroup
+
+### Invariants
+
+- All account group mutation operations (create, update, move, delete) require the parent CoA to be in DRAFT or ACTIVE status; operations on groups under an ARCHIVED CoA are rejected
+- Account group code is required and must be unique within its CoA
+- Account group code is immutable after creation; it cannot be changed via updateAccountGroup
+- Account group name is required and must be non-empty
+- A group with no parent reference is treated as a root-level group
+- A group with a parent reference must reference a valid group within the same CoA
+- Circular parent references are rejected (a group cannot be its own ancestor)
+- Hierarchy depth is not artificially limited but must remain acyclic
+- Sort order controls the display sequence of sibling groups under the same parent
+- Account number range, when defined, must be a valid non-overlapping interval within the CoA
+- Accounts assigned to a group must have account numbers within the group's allowed range (when a range is defined)
+- A group that contains child groups or assigned accounts cannot be deleted
+- Moving a group to a new parent within the same CoA updates the hierarchy without breaking existing account assignments
+- Account group assignment is optional; accounts can exist in a CoA without belonging to any group
+- All account group operations (create, update, move, delete) emit audit events via the audit module recording the acting user, timestamp, and relevant field values
+
+### Relationships
+
+- **References ChartOfAccounts**: Each group belongs to a ChartOfAccounts via chartOfAccountsId
+- **Self-Referential Parent-Child**: Each group optionally references another AccountGroup as its parent, forming a tree
+- **Referenced By Accounts**: Accounts optionally reference an AccountGroup for hierarchical organization

package/src/modules/coa-management/docs/models/ChartOfAccounts.md

@@ -0,0 +1,65 @@
+# ChartOfAccounts
+
+## Description
+
+ChartOfAccounts is the top-level container that organizes all GL accounts and account groups 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. 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.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createChartOfAccounts
+    Draft --> Active: activateChartOfAccounts
+    Active --> Archived: deactivateChartOfAccounts
+    Draft --> [*]: deleteChartOfAccounts
+```
+
+### Command Definitions
+
+- [createChartOfAccounts](../commands/CreateChartOfAccounts.md) - Create a new CoA in DRAFT status for a company
+- [updateChartOfAccounts](../commands/UpdateChartOfAccounts.md) - Update mutable fields (name, description) of an existing CoA
+- [activateChartOfAccounts](../commands/ActivateChartOfAccounts.md) - Transition CoA from DRAFT to ACTIVE
+- [deactivateChartOfAccounts](../commands/DeactivateChartOfAccounts.md) - Transition CoA from ACTIVE to ARCHIVED
+- [deleteChartOfAccounts](../commands/DeleteChartOfAccounts.md) - Permanently delete a DRAFT CoA
+
+### Query Definitions
+
+- [GetChartOfAccounts](../queries/GetChartOfAccounts.md) - Retrieve a CoA by id or companyId
+- [ListAccounts](../queries/ListAccounts.md) - List accounts within this CoA (cross-reference)
+- [ListAccountGroups](../queries/ListAccountGroups.md) - List account groups within this CoA (cross-reference)
+
+### Models
+
+- ChartOfAccounts
+
+### Invariants
+
+- CoA name is required and must be non-empty
+- CoA description is optional and can be updated while in DRAFT or ACTIVE status
+- CoA must reference a valid companyId from the organization module
+- The referenced company must be in ACTIVE status at CoA creation time; creating a CoA for a DRAFT or INACTIVE company is rejected
+- CoA inherits its base currency from the parent company; the company must have a base currency assigned (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 second CoA for the same company fails with a uniqueness constraint error
+- Activating an already ACTIVE CoA fails with an invalid status transition error
+- Archiving a DRAFT CoA fails with an invalid status transition error (only ACTIVE CoA can be archived)
+- Reactivating an ARCHIVED CoA is not permitted (one-way transition from ACTIVE to ARCHIVED)
+- Only DRAFT CoA records can be deleted; ACTIVE and ARCHIVED records are preserved
+- Deleting a DRAFT CoA cascade-deletes all child Account and AccountGroup records; since the CoA is DRAFT, all child accounts are guaranteed to be in DRAFT status with no posted transactions
+- GL accounts can be created under a CoA in DRAFT or ACTIVE status
+- Only accounts under an ACTIVE CoA can receive journal postings from downstream modules
+- All CoA lifecycle operations (create, update, activate, deactivate/archive, delete) emit audit events via the audit module recording the acting user, timestamp, and relevant field values
+
+### Relationships
+
+- **References Company**: Each CoA references a Company from the organization module via companyId
+- **References Currency**: CoA persists the base currency inherited from the parent Company at creation time via baseCurrencyId (foreign key to Currency from the primitives module)
+- **Referenced By Accounts**: GL accounts belong to a CoA (one-to-many)
+- **Referenced By AccountGroups**: Account groups belong to a CoA (one-to-many)
+- **Referenced By Downstream Modules**: The general-ledger module requires an ACTIVE CoA before journal postings are permitted
+- **Template Provider (external dependency)**: CoA creation optionally accepts a templateId resolved by an external template provider. Templates are immutable snapshots containing pre-defined account groups and GL accounts. Template storage, versioning, and catalog management are outside the scope of this module

package/src/modules/coa-management/docs/queries/DetectCircularReference.md

@@ -0,0 +1,52 @@
+# DetectCircularReference
+
+## Overview
+
+DetectCircularReference validates that reparenting an account group would not create a circular reference in the tree hierarchy. It walks up the ancestor chain from the proposed new parent, checking whether the group being moved appears as an ancestor. If the moved group is found in the ancestor chain, the move would create a cycle.
+
+## Business Rules
+
+- Accepts `groupId` (the group being moved) and `newParentId` (the proposed new parent)
+- Returns `{ isCircular: boolean }` — true if the move would create a cycle, false otherwise
+- A group cannot be moved to become a descendant of itself
+- Self-referencing is explicitly rejected: newParentId === groupId
+- Ancestor chain is traversed from the new parent upward to the root
+- If the moved group's ID is found in the ancestor chain, the move is circular
+- Traversal stops at root (parentAccountGroupId = null) or broken chain (parent not found)
+- Only relevant when newParentId is non-null (promoting to root cannot create a cycle)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive groupId + newParentId] --> B{newParentId === groupId?}
+    B -->|Yes| C[Return isCircular: true]
+    B -->|No| D[Set ancestorId = newParentId]
+    D --> E[SELECT ancestor where id = ancestorId]
+    E --> F{Ancestor found?}
+    F -->|No| G[Return isCircular: false]
+    F -->|Yes| H[Set ancestorId = ancestor.parentAccountGroupId]
+    H --> I{ancestorId === groupId?}
+    I -->|Yes| C
+    I -->|No| J{ancestorId is null?}
+    J -->|Yes| G
+    J -->|No| E
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CIRCULAR_REFERENCE**: The moved group appears in the ancestor chain of the new parent — returns isCircular: true
+- **SELF_REFERENCE**: Group is moved to itself as parent — returns isCircular: true
+
+## Test Cases
+
+- detects self-reference as circular
+- detects moving group under its child as circular
+- detects moving group under its grandchild as circular
+- returns not circular for valid move
+- returns not circular when new parent is root
+- handles broken ancestor chain gracefully (not circular)

package/src/modules/coa-management/docs/queries/GetAccount.md

@@ -0,0 +1,42 @@
+# GetAccount
+
+## Overview
+
+GetAccount retrieves a single GL account record by id or by code within a CoA. The input is a union type — callers specify exactly one lookup variant. This serves as the core account lookup for existence checks, uniqueness validation, and all account lifecycle commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier
+  - `{ chartOfAccountsId, code }` — retrieves by account code within a specific CoA
+- Returns the full account record including all fields (id, chartOfAccountsId, accountGroupId, code, name, accountType, classification, currencyRestriction, reconciliation, defaultTaxCode, tags, status, successorAccountId, hasPostedTransactions, timestamps)
+- Returns null if no matching account is found
+- All comparisons are exact
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which variant?}
+    B -->|id| C[SELECT from Account where id = input.id]
+    B -->|chartOfAccountsId + code| D[SELECT from Account where chartOfAccountsId = input.chartOfAccountsId AND code = input.code]
+    C --> E{Account found?}
+    D --> E
+    E -->|Yes| F[Return account record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: No account matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns account when found by id
+- returns null when account not found by id
+- returns account when found by code within CoA
+- returns null when account not found by code within CoA

package/src/modules/coa-management/docs/queries/GetAccountGroup.md

@@ -0,0 +1,42 @@
+# GetAccountGroup
+
+## Overview
+
+GetAccountGroup retrieves a single account group record by id or by code within a CoA. The input is a union type — callers specify exactly one lookup variant. This serves as the core group lookup for existence checks, hierarchy validation, and group management commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier
+  - `{ chartOfAccountsId, code }` — retrieves by group code within a specific CoA
+- Returns the full group record including all fields (id, chartOfAccountsId, parentAccountGroupId, code, name, sortOrder, rangeStart, rangeEnd, timestamps)
+- Returns null if no matching group is found
+- All comparisons are exact
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which variant?}
+    B -->|id| C[SELECT from AccountGroup where id = input.id]
+    B -->|chartOfAccountsId + code| D[SELECT from AccountGroup where chartOfAccountsId = input.chartOfAccountsId AND code = input.code]
+    C --> E{Group found?}
+    D --> E
+    E -->|Yes| F[Return group record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_GROUP_NOT_FOUND**: No group matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns group when found by id
+- returns null when group not found by id
+- returns group when found by code within CoA
+- returns null when group not found by code within CoA

package/src/modules/coa-management/docs/queries/GetChartOfAccounts.md

@@ -0,0 +1,48 @@
+# GetChartOfAccounts
+
+## Overview
+
+GetChartOfAccounts retrieves a single Chart of Accounts record by id or by companyId. The input is a union type — callers specify exactly one lookup field. This serves as the core CoA lookup for existence checks, company-scoped retrieval, and all CoA lifecycle commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier
+  - `{ companyId, status? }` — retrieves the CoA for a specific company, optionally filtered by status (e.g., pass `ACTIVE` to find the current active CoA for uniqueness checks during activation)
+- When looking up by companyId without a status filter, returns the most recently created CoA
+- Returns the full CoA record including all fields (id, companyId, name, description, baseCurrencyId, status, timestamps)
+- Returns null if no matching CoA is found
+- All comparisons are exact
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which variant?}
+    B -->|id| C[SELECT from ChartOfAccounts where id = input.id]
+    B -->|companyId| D{Status filter provided?}
+    D -->|Yes| D1[SELECT from ChartOfAccounts where companyId = input.companyId AND status = input.status]
+    D -->|No| D2[SELECT from ChartOfAccounts where companyId = input.companyId ORDER BY createdAt DESC LIMIT 1]
+    C --> E{CoA found?}
+    D1 --> E
+    D2 --> E
+    E -->|Yes| F[Return CoA record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: No CoA matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns CoA when found by id
+- returns null when CoA not found by id
+- returns CoA when found by companyId
+- returns null when CoA not found by companyId
+- returns CoA when found by companyId with status filter
+- returns null when no CoA matches companyId and status filter

package/src/modules/coa-management/docs/queries/ListAccountGroups.md

@@ -0,0 +1,42 @@
+# ListAccountGroups
+
+## Overview
+
+ListAccountGroups retrieves account groups within a Chart of Accounts, optionally filtered by parent group. This supports hierarchical tree traversal by enabling consumers to query root groups (parent = null) or children of a specific parent. Results are sorted by sort order within each sibling set.
+
+## Business Rules
+
+- chartOfAccountsId is required — groups are always scoped to a CoA
+- Optional filter:
+  - `parentAccountGroupId` — filter by parent group (null for root groups)
+- Returns full group records (same shape as GetAccountGroup output)
+- Results are sorted by sortOrder ascending within each sibling set
+- Returns an empty list if no groups match
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with chartOfAccountsId] --> B{Parent filter provided?}
+    B -->|Yes| C[SELECT groups where parentAccountGroupId = input.parentAccountGroupId]
+    B -->|No| D[SELECT all groups in CoA]
+    C --> E[Sort by sortOrder ascending]
+    D --> E
+    E --> F[Return group list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **EMPTY_RESULT**: No groups match the given criteria — returns empty list
+
+## Test Cases
+
+- returns all groups in a CoA when no parent filter applied
+- returns root groups when parent filter is null
+- returns child groups of a specific parent
+- returns groups sorted by sort order
+- returns empty list when no groups match

package/src/modules/coa-management/docs/queries/ListAccounts.md

@@ -0,0 +1,54 @@
+# ListAccounts
+
+## Overview
+
+ListAccounts retrieves a list of GL accounts within a Chart of Accounts, with optional filters for type, classification, account group, tags, status, and currency restriction. Results are sorted by account code by default.
+
+## Business Rules
+
+- chartOfAccountsId is required — accounts are always scoped to a CoA
+- Optional filters:
+  - `accountType` — filter by ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE
+  - `accountClassification` — filter by REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, or NON_POSTING
+  - `accountGroupId` — filter by account group membership
+  - `tags` — filter by one or more tag labels (accounts matching any of the provided tags)
+  - `status` — filter by DRAFT, ACTIVE, or INACTIVE
+  - `currencyRestriction` — filter by currency code
+- All filters can be combined; when multiple filters are provided, results must match all criteria (AND logic)
+- Returns full account records (same shape as GetAccount output)
+- Results are sorted by account code ascending by default
+- Returns an empty list if no accounts match the filters
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with chartOfAccountsId] --> B[Build query with CoA scope]
+    B --> C{Filters provided?}
+    C -->|Yes| D[Apply filters to query]
+    C -->|No| E[Return all accounts in CoA]
+    D --> E
+    E --> F[Sort by account code ascending]
+    F --> G[Return account list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **EMPTY_RESULT**: No accounts match the given criteria — returns empty list
+
+## Test Cases
+
+- returns all accounts in a CoA when no filters applied
+- returns accounts filtered by account type
+- returns accounts filtered by classification
+- returns accounts filtered by account group
+- returns accounts filtered by tags (matches accounts having any of the provided tags)
+- returns accounts filtered by status
+- returns accounts filtered by currency restriction
+- returns accounts filtered by multiple criteria combined
+- returns accounts sorted by code ascending
+- returns empty list when no accounts match

package/src/modules/coa-management/docs/queries/ListUnassignedAccounts.md

@@ -0,0 +1,40 @@
+# ListUnassignedAccounts
+
+## Overview
+
+ListUnassignedAccounts retrieves all active accounts within a Chart of Accounts that are not assigned to any account group. This enables downstream consumers (e.g., reporting module) to validate hierarchy completeness according to their own requirements.
+
+## Business Rules
+
+- chartOfAccountsId is required — accounts are always scoped to a CoA
+- Returns only accounts where accountGroupId is null
+- Returns only ACTIVE accounts (DRAFT and INACTIVE accounts are excluded as they are not yet or no longer operationally relevant for hierarchy completeness checks)
+- Returns full account records (same shape as GetAccount output)
+- Results are sorted by account code ascending
+- Returns an empty list if all active accounts are assigned to groups
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with chartOfAccountsId] --> B[SELECT accounts where chartOfAccountsId = input AND accountGroupId IS NULL AND status = ACTIVE]
+    B --> C[Sort by account code ascending]
+    C --> D[Return unassigned account list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **EMPTY_RESULT**: No unassigned active accounts found — returns empty list
+
+## Test Cases
+
+- returns unassigned active accounts in a CoA
+- excludes accounts that are assigned to a group
+- excludes DRAFT accounts
+- excludes INACTIVE accounts
+- returns accounts sorted by code ascending
+- returns empty list when all active accounts are assigned