@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/coa-management/db/chartOfAccounts.ts

@@ -0,0 +1,55 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub, currency as currencyStub } from "../lib/_db_deps";
+
+export const BASE_COA_STATUSES = ["DRAFT", "ACTIVE", "ARCHIVED"] as const;
+
+export interface CreateChartOfAccountsTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+  companyType?: TailorAnyDBType;
+  currencyType?: TailorAnyDBType;
+}
+
+export function createChartOfAccountsType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateChartOfAccountsTypeParams<F>,
+) {
+  const statuses = [...BASE_COA_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type(["ChartOfAccounts", "ChartsOfAccounts"], {
+      name: db.string().description("Name of the chart of accounts"),
+      description: db.string({ optional: true }).description("Optional description of the CoA"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "chartOfAccounts",
+        })
+        .description("Foreign key to Company from organization module"),
+      baseCurrencyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "chartsOfAccounts",
+        })
+        .description("Base currency inherited from the parent company at creation time"),
+      status: db.enum(statuses).description("Lifecycle status: DRAFT, ACTIVE, ARCHIVED"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const chartOfAccounts = createChartOfAccountsType({});

package/src/modules/coa-management/docs/commands/ActivateAccount.md

@@ -0,0 +1,49 @@
+# ActivateAccount
+
+## Overview
+
+activateAccount transitions a GL account from DRAFT to ACTIVE status, making it eligible to receive journal postings from downstream modules. Only DRAFT accounts can be activated; already ACTIVE or INACTIVE accounts require different transitions.
+
+## Business Rules
+
+- Target account must exist
+- Parent CoA must be in ACTIVE status; activating an account under a DRAFT CoA is rejected because the CoA itself has not yet been activated, and activating an account under an ARCHIVED CoA is rejected because archived CoAs are immutable
+- Target account must be in DRAFT status
+- Activating an already ACTIVE account fails with an invalid state transition error
+- Activating an INACTIVE account fails (use reactivateAccount instead)
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, and status transition from DRAFT to ACTIVE
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Account exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is not ACTIVE]
+    B2 -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return activated account]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
+- **CHART_OF_ACCOUNTS_NOT_ACTIVE**: Parent CoA is not in ACTIVE status; account activation requires the CoA to be ACTIVE
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+
+## Test Cases
+
+- returns error when account does not exist
+- returns error when parent CoA is DRAFT
+- returns error when parent CoA is ARCHIVED
+- returns error when account is already ACTIVE
+- returns error when account is INACTIVE
+- activates a DRAFT account
+- emits audit event recording status transition from DRAFT to ACTIVE

package/src/modules/coa-management/docs/commands/ActivateChartOfAccounts.md

@@ -0,0 +1,47 @@
+# ActivateChartOfAccounts
+
+## Overview
+
+activateChartOfAccounts transitions a Chart of Accounts from DRAFT to ACTIVE status. Activation makes the CoA the authoritative account structure for its company, enabling accounts within it to receive journal postings from downstream modules. Only one CoA per company can be ACTIVE at a time.
+
+## Business Rules
+
+- Target CoA must exist
+- Target CoA must be in DRAFT status
+- Activating an already ACTIVE or ARCHIVED CoA fails with an invalid state transition error
+- Only one CoA per company can be in ACTIVE status; activating a second CoA for the same company fails with a uniqueness constraint error
+- Emits an audit event via the audit module recording the acting user, timestamp, and status transition from DRAFT to ACTIVE
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{CoA exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F{Another ACTIVE CoA for same company?}
+    F -->|Yes| G[Return error: duplicate active CoA]
+    F -->|No| H[Update status to ACTIVE]
+    H --> I[Emit audit event]
+    I --> J[Return activated CoA]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Specified CoA ID does not exist
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+- **DUPLICATE_ACTIVE_CHART_OF_ACCOUNTS**: Another ACTIVE CoA already exists for the same company
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when CoA is already ACTIVE
+- returns error when CoA is ARCHIVED
+- returns error when another ACTIVE CoA exists for the same company
+- activates a DRAFT CoA
+- emits audit event recording status transition from DRAFT to ACTIVE

package/src/modules/coa-management/docs/commands/CreateAccount.md

@@ -0,0 +1,94 @@
+# CreateAccount
+
+## Overview
+
+createAccount establishes a new GL account in DRAFT status within a Chart of Accounts. Each account carries a structured numeric code, name, account type, account classification, and optional attributes (currency restriction, reconciliation flag, default tax code, tags, account group assignment). The parent CoA must be in DRAFT or ACTIVE status.
+
+## Business Rules
+
+- Account code is required, must be a structured numeric identifier, and must be unique within the CoA
+- 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; defaults to REGULAR
+- Classification must be compatible with account type: RECEIVABLE, BANK_CASH, and FIXED_ASSET require ASSET; PAYABLE requires LIABILITY; RETAINED_EARNINGS requires EQUITY; REGULAR and NON_POSTING are allowed with any type
+- Only one account per CoA may carry the RETAINED_EARNINGS classification
+- Accounts with RECEIVABLE, PAYABLE, or BANK_CASH classification must have reconciliation enabled; attempting to set reconciliation to false for these classifications is rejected
+- Reconciliation flag defaults to false when not explicitly set for REGULAR, FIXED_ASSET, RETAINED_EARNINGS, and NON_POSTING classifications
+- NON_POSTING classification marks the account as excluded from journal entry posting target selection; this constraint is stored on the account and enforced by downstream posting modules
+- RECEIVABLE and PAYABLE classifications mark the account as a sub-ledger control account; direct manual journal postings are blocked (only automated sub-ledger module postings are permitted). This constraint is stored on the account and enforced by the GL/posting layer
+- Currency restriction, when provided, must reference a valid currency from the primitives module. An account with currency restriction only accepts postings denominated in that currency (enforced by downstream posting modules)
+- Account group, when provided, must belong to the same CoA and account code must fall within the group's number range (if defined)
+- Parent CoA must exist and be in DRAFT or ACTIVE status
+- Account is always created in DRAFT status
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, classification, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{CoA exists and is DRAFT or ACTIVE?}
+    B -->|No| C[Return error: CoA not found or invalid status]
+    B -->|Yes| D{Account code unique within CoA?}
+    D -->|No| E[Return error: duplicate code]
+    D -->|Yes| F{Classification compatible with type?}
+    F -->|No| G[Return error: incompatible classification]
+    F -->|Yes| H{RETAINED_EARNINGS unique in CoA?}
+    H -->|No| I[Return error: duplicate retained earnings]
+    H -->|Yes| J{Currency valid if provided?}
+    J -->|No| K[Return error: currency not found]
+    J -->|Yes| L{Group valid if provided?}
+    L -->|No| M[Return error: group not found or code out of range]
+    L -->|Yes| N{Reconciliation valid for classification?}
+    N -->|No| Q[Return error: reconciliation required]
+    N -->|Yes| O[Create account in DRAFT]
+    O --> P[Emit audit event]
+    P --> Q[Return created account]
+```
+
+## External Dependencies
+
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the referenced currency exists and is active
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Referenced CoA does not exist or is not in DRAFT/ACTIVE status
+- **DUPLICATE_ACCOUNT_CODE**: An account with the same code already exists in the CoA
+- **INCOMPATIBLE_CLASSIFICATION**: Account classification is not compatible with the account type
+- **DUPLICATE_RETAINED_EARNINGS**: Another account in the CoA already has RETAINED_EARNINGS classification
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist or is not active
+- **ACCOUNT_GROUP_NOT_FOUND**: Referenced account group does not exist or belongs to a different CoA
+- **CODE_OUT_OF_RANGE**: Account code does not fall within the assigned group's number range
+- **NAME_REQUIRED**: Account name is empty or not provided
+- **INVALID_ACCOUNT_CODE**: Account code is not a valid structured numeric identifier
+- **RECONCILIATION_REQUIRED**: Reconciliation cannot be set to false for RECEIVABLE, PAYABLE, or BANK_CASH classifications
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when CoA is ARCHIVED
+- returns error when account code already exists in CoA
+- returns error when account code is not a valid numeric identifier
+- returns error when name is empty
+- returns error when classification is incompatible with type
+- returns error when RETAINED_EARNINGS already exists in CoA
+- returns error when currency does not exist
+- returns error when account group belongs to different CoA
+- returns error when account code is outside group number range
+- creates account in DRAFT status with defaults
+- creates account with RECEIVABLE classification and enforces reconciliation
+- creates account with PAYABLE classification and enforces reconciliation
+- creates account with BANK_CASH classification and enforces reconciliation
+- creates NON_POSTING account that is marked as excluded from journal entry posting
+- creates RECEIVABLE account that is marked as control account blocking manual postings
+- creates PAYABLE account that is marked as control account blocking manual postings
+- creates account with currency restriction that constrains posting currency
+- creates account with optional currency restriction
+- creates account with optional tags
+- creates account with optional default tax code
+- creates account assigned to a group
+- defaults classification to REGULAR when not specified
+- returns error when reconciliation explicitly set to false for RECEIVABLE classification
+- returns error when reconciliation explicitly set to false for PAYABLE classification
+- returns error when reconciliation explicitly set to false for BANK_CASH classification
+- emits audit event recording acting user, timestamp, CoA reference, account code, and classification
+- passes custom fields through to insert

package/src/modules/coa-management/docs/commands/CreateAccountGroup.md

@@ -0,0 +1,70 @@
+# CreateAccountGroup
+
+## Overview
+
+createAccountGroup establishes a new account group within a Chart of Accounts. Groups organize GL accounts into logical categories and can be nested to form a multi-level tree hierarchy. Each group has a code, name, optional parent reference, sort order, and optional account number range.
+
+## Business Rules
+
+- Parent CoA must exist and be in DRAFT or ACTIVE status; creating a group under an ARCHIVED CoA is rejected
+- Group code is required and must be unique within the CoA
+- Group name is required and must be non-empty
+- Parent group, when provided, must exist within the same CoA
+- Account number range, when defined, requires both start and end to be provided together, must be a valid interval (start < end), and must not overlap with other groups' ranges within the CoA
+- Sort order controls display sequence among sibling groups
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, group code, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{CoA exists?}
+    B -->|No| C[Return error: CoA not found]
+    B -->|Yes| B2{CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| C2{Code non-empty?}
+    C2 -->|No| C3[Return error: code required]
+    C2 -->|Yes| D{Code unique within CoA?}
+    D -->|No| E[Return error: duplicate code]
+    D -->|Yes| F{Parent group valid if provided?}
+    F -->|No| G[Return error: parent not found]
+    F -->|Yes| H{Number range valid and non-overlapping?}
+    H -->|No| I[Return error: invalid or overlapping range]
+    H -->|Yes| J[Create account group]
+    J --> K[Emit audit event]
+    K --> L[Return created group]
+```
+
+## External Dependencies
+
+- [audit](../../../audit/README.md) — Receives audit events emitted by this command
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Referenced CoA does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **CODE_REQUIRED**: Group code is empty or not provided
+- **DUPLICATE_GROUP_CODE**: A group with the same code already exists in the CoA
+- **NAME_REQUIRED**: Group name is empty or not provided
+- **PARENT_GROUP_NOT_FOUND**: Specified parent group does not exist or belongs to a different CoA
+- **INVALID_NUMBER_RANGE**: Number range is invalid (start >= end) or overlaps with another group's range
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when group code is empty
+- returns error when group code already exists in CoA
+- returns error when name is empty
+- returns error when parent group does not exist
+- returns error when parent group belongs to different CoA
+- returns error when number range is invalid
+- returns error when number range overlaps with existing group
+- returns error when only numberRangeStart is provided
+- returns error when only numberRangeEnd is provided
+- creates a root group with no parent
+- creates a child group with valid parent
+- creates a group with account number range
+- creates a group with sort order
+- emits audit event recording acting user, timestamp, CoA reference, group code, and initial field values
+- passes custom fields through to insert

package/src/modules/coa-management/docs/commands/CreateChartOfAccounts.md

@@ -0,0 +1,72 @@
+# CreateChartOfAccounts
+
+## Overview
+
+createChartOfAccounts establishes a new Chart of Accounts container in DRAFT status for a company. The CoA inherits its base currency from the parent company. The referenced company must be in ACTIVE status, which guarantees structural identity completeness including base currency assignment.
+
+## Business Rules
+
+- 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
+- CoA is always created in DRAFT status
+- Description is optional
+- An optional `templateId` can be provided to initialize the CoA from a country-specific localized template; when omitted, a blank CoA is created with no pre-populated account groups or accounts
+- Templates are externally managed configuration data (not owned by this module). Each template is an immutable snapshot containing pre-defined account groups (with numbering ranges) and GL accounts for a specific country or industry. Template storage, versioning, and catalog management are outside the scope of coa-management
+- When `templateId` is provided, the command delegates template resolution to the template provider (external dependency). The provider must return the template's account groups and accounts. If no template provider is configured, templateId is rejected with TEMPLATE_PROVIDER_NOT_CONFIGURED
+- When a valid template is resolved, the command copies the template's account groups (with numbering ranges) and GL accounts into the new CoA in DRAFT status
+- Template-based creation is a convenience shortcut — all copied entities are fully mutable in DRAFT and can be modified before activation
+- Emits an audit event via the audit module recording the acting user, timestamp, initial field values, and whether the CoA was created from a template or blank
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: company not found or not active]
+    B -->|Yes| D{Name non-empty?}
+    D -->|No| E[Return error: name required]
+    D -->|Yes| F[Inherit base currency from company]
+    F --> G{templateId provided?}
+    G -->|Yes| G2{Template provider configured?}
+    G2 -->|No| G3[Return error: template provider not configured]
+    G2 -->|Yes| H{Template exists and is valid?}
+    H -->|No| I[Return error: template not found]
+    H -->|Yes| J[Create CoA in DRAFT with template contents]
+    G -->|No| K[Create blank CoA in DRAFT]
+    J --> L[Emit audit event]
+    K --> L
+    L --> M[Return created CoA]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates that the referenced company exists and is ACTIVE
+- **Template Provider (external)** - Resolves templateId to a template snapshot containing account groups and GL accounts. Template storage, versioning, and catalog management are outside the scope of this module. When no template provider is configured, only blank CoA creation is available
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **NAME_REQUIRED**: CoA name is empty or not provided
+- **TEMPLATE_NOT_FOUND**: Specified templateId does not reference a valid template in the template provider
+- **TEMPLATE_PROVIDER_NOT_CONFIGURED**: templateId was provided but no template provider is configured
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when name is empty
+- returns error when templateId is provided but no template provider is configured
+- returns error when templateId does not reference a valid template
+- creates blank CoA in DRAFT status when no templateId is provided
+- creates CoA from template with pre-populated account groups and accounts in DRAFT status
+- creates CoA from template with nested groups provided in child-first order
+- creates CoA with optional description
+- passes custom fields through to insert
+- validates company via organizationQueries when provided
+- returns error when organizationQueries reports company not found
+- creates blank CoA in DRAFT status with inherited base currency when no templateId is provided
+- template-copied entities are mutable and can be modified before activation
+- emits audit event recording acting user, timestamp, and initial field values
+- audit event includes whether CoA was created from template or blank

package/src/modules/coa-management/docs/commands/DeactivateAccount.md

@@ -0,0 +1,65 @@
+# DeactivateAccount
+
+## Overview
+
+deactivateAccount transitions a GL account from ACTIVE to INACTIVE status, preventing new journal postings while preserving the account and its history for regulatory reporting and audit purposes. An optional successor account can be designated during deactivation; posting redirection is owned by the general-ledger module. A pre-deactivation hook is exposed for the GL module to block deactivation when open or unreconciled balances exist.
+
+## Business Rules
+
+- Target account must exist
+- Parent CoA must be in ACTIVE status; deactivating an account under an ARCHIVED CoA is rejected. Note: the DRAFT CoA case is unreachable because account activation requires an ACTIVE CoA, so an ACTIVE account cannot exist under a DRAFT CoA
+- Target account must be in ACTIVE status
+- Deactivating a DRAFT account fails with an invalid state transition error
+- A successor account, when provided, must be ACTIVE at the time of mapping
+- Deactivation exposes a pre-deactivation hook for the GL module to block the transition when open balances exist
+- Without a GL module integrated, deactivation proceeds without balance checks
+- Successor account mapping is optional
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, status transition from ACTIVE to INACTIVE, and successor mapping if provided
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Account exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is not ACTIVE]
+    B2 -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F{Pre-deactivation hook registered?}
+    F -->|Yes| G{Balance check passes?}
+    G -->|No| H[Return error: open balances]
+    G -->|Yes| I{Successor provided?}
+    F -->|No| I
+    I -->|Yes| J{Successor is ACTIVE?}
+    J -->|No| K[Return error: successor not active]
+    J -->|Yes| L[Map successor and set INACTIVE]
+    I -->|No| L[Set status to INACTIVE]
+    L --> M[Emit audit event]
+    M --> N[Return deactivated account]
+```
+
+## External Dependencies
+
+- None (GL module balance check is an optional integration hook)
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+- **OPEN_BALANCES_EXIST**: Pre-deactivation hook reports open or unreconciled balances (GL module integration)
+- **SUCCESSOR_NOT_ACTIVE**: Specified successor account is not in ACTIVE status
+
+## Test Cases
+
+- returns error when account does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when account is not ACTIVE
+- returns error when account is DRAFT
+- returns error when successor account is not ACTIVE
+- deactivates an ACTIVE account without successor
+- deactivates an ACTIVE account with successor mapping
+- deactivates without balance check when GL hook is not registered
+- returns error when GL hook reports open balances
+- emits audit event recording status transition from ACTIVE to INACTIVE and successor mapping

package/src/modules/coa-management/docs/commands/DeactivateChartOfAccounts.md

@@ -0,0 +1,44 @@
+# DeactivateChartOfAccounts
+
+## Overview
+
+deactivateChartOfAccounts transitions a Chart of Accounts from ACTIVE to ARCHIVED status. Archiving permanently retires the CoA while preserving the historical account structure for audit and restatement purposes. This is a one-way transition — ARCHIVED CoA records cannot be reactivated. The command name follows the canonical verb convention (`deactivate` instead of `archive`); the target status is ARCHIVED.
+
+## Business Rules
+
+- Target CoA must exist
+- Target CoA must be in ACTIVE status
+- Deactivating a DRAFT or already ARCHIVED CoA fails with an invalid state transition error
+- Archived CoA records and their accounts remain queryable for reporting and audit
+- This is a one-way transition; reactivation from ARCHIVED is not permitted
+- Emits an audit event via the audit module recording the acting user, timestamp, and status transition from ACTIVE to ARCHIVED
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{CoA exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ARCHIVED]
+    F --> G[Emit audit event]
+    G --> H[Return archived CoA]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Specified CoA ID does not exist
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when CoA is DRAFT
+- returns error when CoA is already ARCHIVED
+- archives an ACTIVE CoA
+- emits audit event recording status transition from ACTIVE to ARCHIVED

package/src/modules/coa-management/docs/commands/DeleteAccount.md

@@ -0,0 +1,52 @@
+# DeleteAccount
+
+## Overview
+
+deleteAccount permanently removes a GL account that is in DRAFT status and has no posted transactions. Accounts in ACTIVE or INACTIVE status cannot be deleted — they must be deactivated instead. Accounts with posted transactions cannot be deleted regardless of status, preserving ledger integrity.
+
+## Business Rules
+
+- Target account must exist
+- Parent CoA must be in DRAFT or ACTIVE status; deleting an account under an ARCHIVED CoA is rejected
+- Target account must be in DRAFT status
+- Target account must have no posted transactions
+- Deleting ACTIVE or INACTIVE accounts is rejected
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, and deletion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Account exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: only DRAFT can be deleted]
+    D -->|Yes| F{Has posted transactions?}
+    F -->|Yes| G[Return error: has posted transactions]
+    F -->|No| H[Delete account record]
+    H --> I[Emit audit event]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+- **HAS_POSTED_TRANSACTIONS**: Account has posted transactions and cannot be deleted
+
+## Test Cases
+
+- returns error when account does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when account is ACTIVE
+- returns error when account is INACTIVE
+- returns error when DRAFT account has posted transactions
+- deletes a DRAFT account with no posted transactions
+- emits audit event recording deletion, acting user, and account code

package/src/modules/coa-management/docs/commands/DeleteAccountGroup.md

@@ -0,0 +1,50 @@
+# DeleteAccountGroup
+
+## Overview
+
+deleteAccountGroup permanently removes an account group that has no child groups and no assigned accounts. Groups with children or assigned accounts must have those relationships resolved before deletion.
+
+## Business Rules
+
+- Target group must exist
+- Parent CoA must be in DRAFT or ACTIVE status; deleting a group under an ARCHIVED CoA is rejected
+- Group must have no child groups
+- Group must have no accounts assigned to it
+- Emits an audit event via the audit module recording the acting user, timestamp, and deletion of the group
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Group exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| D{Has child groups?}
+    D -->|Yes| E[Return error: has children]
+    D -->|No| F{Has assigned accounts?}
+    F -->|Yes| G[Return error: has assigned accounts]
+    F -->|No| H[Delete group]
+    H --> I[Emit audit event]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_GROUP_NOT_FOUND**: Specified group ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **HAS_CHILD_GROUPS**: Group contains child groups and cannot be deleted
+- **HAS_ASSIGNED_ACCOUNTS**: Group has accounts assigned to it and cannot be deleted
+
+## Test Cases
+
+- returns error when group does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when group has child groups
+- returns error when group has assigned accounts
+- deletes a leaf group with no assigned accounts
+- emits audit event recording deletion and acting user

package/src/modules/coa-management/docs/commands/DeleteChartOfAccounts.md

@@ -0,0 +1,48 @@
+# DeleteChartOfAccounts
+
+## Overview
+
+deleteChartOfAccounts permanently removes a Chart of Accounts that is still in DRAFT status. Only DRAFT CoA records can be deleted. ACTIVE and ARCHIVED records are preserved for operational and audit purposes.
+
+## Business Rules
+
+- Target CoA must exist
+- Target CoA must be in DRAFT status; deleting ACTIVE or ARCHIVED CoA is rejected
+- Deletion cascade-deletes all child Account and AccountGroup records belonging to the CoA. Because only DRAFT CoA records can be deleted, and accounts can only be created under a DRAFT or ACTIVE CoA, all child accounts are guaranteed to be in DRAFT status with no posted transactions at this point — making cascade deletion safe and consistent with the account deletion invariant
+- Each cascade-deleted child record (Account and AccountGroup) emits its own audit event, followed by the CoA deletion audit event
+- Emits an audit event via the audit module recording the acting user, timestamp, and deletion of the CoA
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{CoA exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: only DRAFT can be deleted]
+    D -->|Yes| F[Cascade-delete all child Accounts]
+    F --> G[Cascade-delete all child AccountGroups]
+    G --> H[Delete CoA record]
+    H --> I[Emit audit events for each deleted child and the CoA]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Specified CoA ID does not exist
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when CoA is ACTIVE
+- returns error when CoA is ARCHIVED
+- deletes a DRAFT CoA with no child records
+- deletes a DRAFT CoA and cascade-deletes all child Accounts
+- deletes a DRAFT CoA and cascade-deletes all child AccountGroups
+- emits audit events for each cascade-deleted Account and AccountGroup
+- emits audit event recording CoA deletion and acting user