# 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
