@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/accounting/docs/models/CostElement.md

@@ -0,0 +1,66 @@
+# CostElement
+
+## Description
+
+CostElement is the foundational classification entity of the accounting module, defining the types of costs that can be recorded, allocated, and analyzed across cost centers, profit centers, and internal orders. Each cost element carries a code, name, type (PRIMARY or SECONDARY), category, optional description, optional GL account reference (mandatory for primary elements), company scope, and optional validity period. Primary cost elements are mapped one-to-one to GL accounts from coa-management and represent costs visible in both financial and management accounting (e.g., material costs, labor costs, depreciation). Secondary cost elements exist exclusively within the controlling domain for internal cost allocation activities such as assessment, distribution, and settlement. Cost elements follow a lifecycle from DRAFT through ACTIVE to INACTIVE, ensuring that only validated cost types are available for postings.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createCostElement
+    Draft --> Draft: updateCostElement
+    Draft --> Active: activateCostElement
+    Active --> Inactive: deactivateCostElement
+    Inactive --> Active: reactivateCostElement
+    Draft --> [*]: deleteCostElement
+```
+
+### Command Definitions
+
+- [createCostElement](../commands/CreateCostElement.md) - Create a new cost element in DRAFT status with code, name, type, category, and optional GL account reference
+- [updateCostElement](../commands/UpdateCostElement.md) - Update mutable fields of a cost element (name, description, validity dates)
+- [activateCostElement](../commands/ActivateCostElement.md) - Activate a DRAFT cost element, making it available for cost postings and allocations
+- [deactivateCostElement](../commands/DeactivateCostElement.md) - Deactivate an ACTIVE cost element, preventing new postings while preserving historical data
+- [reactivateCostElement](../commands/ReactivateCostElement.md) - Reactivate an INACTIVE cost element back to ACTIVE status
+- [deleteCostElement](../commands/DeleteCostElement.md) - Delete a DRAFT cost element that has not been activated
+
+### Query Definitions
+
+- [GetCostElement](../queries/GetCostElement.md) - Retrieve a cost element by id
+- [ListCostElements](../queries/ListCostElements.md) - List cost elements with filters (type, category, status, company)
+
+### Models
+
+- CostElement
+
+### Invariants
+
+- Cost elements can only be created in DRAFT status
+- Cost element requires a unique code within the company scope
+- Cost element requires a name and a type (PRIMARY or SECONDARY)
+- Cost element requires a category appropriate to its type: overhead, material, labor, depreciation for PRIMARY; assessment, distribution, internal_activity_allocation, settlement for SECONDARY
+- A primary cost element must reference a valid GL account from an ACTIVE Chart of Accounts; the GL account must be active
+- A secondary cost element must not reference a GL account
+- Two primary cost elements within the same company cannot reference the same GL account
+- A primary cost element's GL account must belong to the same company's chart of accounts
+- Cost element valid-from date must be before or equal to valid-to date when both are provided; omitting them means the element is valid indefinitely
+- Only DRAFT cost elements can be deleted; ACTIVE and INACTIVE elements cannot be deleted
+- Changing the type of a cost element (PRIMARY to SECONDARY or vice versa) after activation is not permitted
+- Changing the GL account reference of a primary cost element after activation is not permitted
+- Updating the category of an ACTIVE cost element is not permitted
+- Cost postings referencing a cost element that is INACTIVE or outside its validity period are rejected
+- Secondary cost elements can only be used in internal allocation contexts (assessment, distribution, activity allocation, settlement)
+- Cost elements are scoped to a company; elements from different companies are fully isolated
+- Cost element must reference a valid companyId; the company must be in ACTIVE status
+
+### Relationships
+
+- **References Company**: Each cost element is scoped to a Company via companyId (organization module)
+- **References GLAccount**: Primary cost elements reference a GLAccount via glAccountId (coa-management module); secondary cost elements have no GL account reference

package/src/modules/accounting/docs/models/InternalOrder.md

@@ -0,0 +1,67 @@
+# InternalOrder
+
+## Description
+
+InternalOrder is a temporary cost collector entity for tracking expenses associated with specific short-to-medium-term activities such as projects, marketing campaigns, R&D initiatives, and corporate events. Each internal order carries a unique order number, order type (OVERHEAD, INVESTMENT, or ACCRUAL), description, responsible person, responsible cost center reference, company scope, optional validity dates, and a status. Unlike cost centers which are permanent organizational units, internal orders are purpose-bound objects with a defined lifecycle that follows a four-stage progression: CREATED, RELEASED, TECHNICALLY_COMPLETED, and CLOSED. Cost postings are only permitted while the order is in RELEASED status, and orders may optionally have a budget assigned to control spending limits.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: createInternalOrder
+    Created --> Released: releaseInternalOrder
+    Released --> TechnicallyCompleted: technicallyCompleteInternalOrder
+    TechnicallyCompleted --> Closed: closeInternalOrder
+    Created --> [*]: deleteInternalOrder
+```
+
+### Command Definitions
+
+- [createInternalOrder](../commands/CreateInternalOrder.md) - Create a new internal order in CREATED status with order type, description, responsible person, and cost center
+- [updateInternalOrder](../commands/UpdateInternalOrder.md) - Update mutable fields of an internal order (description, responsible person, cost center, validity dates)
+- [releaseInternalOrder](../commands/ReleaseInternalOrder.md) - Release a CREATED internal order, enabling cost postings
+- [technicallyCompleteInternalOrder](../commands/TechnicallyCompleteInternalOrder.md) - Technically complete a RELEASED order, stopping new postings and beginning final review
+- [closeInternalOrder](../commands/CloseInternalOrder.md) - Close a TECHNICALLY_COMPLETED order, archiving it permanently
+- [deleteInternalOrder](../commands/DeleteInternalOrder.md) - Delete a CREATED internal order that has not been released
+
+### Query Definitions
+
+- [GetInternalOrder](../queries/GetInternalOrder.md) - Retrieve an internal order by id
+- [ListInternalOrders](../queries/ListInternalOrders.md) - List internal orders with filters (type, status, company, cost center)
+
+### Models
+
+- InternalOrder
+
+### Invariants
+
+- Internal order can only be created in CREATED status
+- Internal order requires a unique order number within the company scope
+- Internal order requires a valid order type (OVERHEAD, INVESTMENT, ACCRUAL)
+- Internal order requires a description and a responsible person
+- Internal order must reference a valid companyId; the company must be in ACTIVE status
+- Internal order must reference a valid responsible cost center within the same company
+- Validity dates are optional; when both are provided, valid-from must precede valid-to
+- Cost postings are only accepted when the internal order is in RELEASED status
+- Cost postings to an order in CREATED, TECHNICALLY_COMPLETED, or CLOSED status are rejected
+- Cost postings with a date outside the order's validity period are rejected when validity dates are set
+- Only CREATED orders can be released; releasing an order in any other status fails
+- Only RELEASED orders can be technically completed
+- Only TECHNICALLY_COMPLETED orders can be closed
+- CLOSED orders cannot transition to any other status
+- Only CREATED orders can be deleted; RELEASED, TECHNICALLY_COMPLETED, and CLOSED orders cannot be deleted
+- Order type cannot be changed after the order is released
+- Internal order fields can be updated while in CREATED or RELEASED status but not in TECHNICALLY_COMPLETED or CLOSED status
+- Cost postings to an internal order with a budget must not exceed the assigned budget amount
+- Internal orders are scoped to a company; orders from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each internal order is scoped to a Company via companyId (organization module)
+- **References CostCenter**: Each internal order references a responsible CostCenter via costCenterId (accounting module)

package/src/modules/accounting/docs/models/PlanVersion.md

@@ -0,0 +1,36 @@
+# PlanVersion
+
+## Description
+
+PlanVersion is a versioning entity that supports multi-version budget planning, enabling organizations to maintain an approved operating budget alongside rolling forecasts and what-if simulations. Each plan version carries a name, type (BUDGET, FORECAST, or SIMULATION), optional base version reference for copying line items, and company scope. The BUDGET type represents the committed baseline, FORECAST enables rolling adjustments to projections, and SIMULATION allows what-if modeling without altering any committed plan. Plan versions can reference a base version from which line items are copied, supporting incremental planning workflows.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createPlanVersion](../commands/CreatePlanVersion.md) - Create a new plan version with name, type, optional base version reference, and company
+
+### Query Definitions
+
+- None — plan versions are accessed through their associated budget queries
+
+### Models
+
+- PlanVersion
+
+### Invariants
+
+- Plan version requires a name
+- Plan version requires a valid type (BUDGET, FORECAST, or SIMULATION)
+- Plan version must reference a valid companyId; the company must be in ACTIVE status
+- Plan version of type FORECAST or SIMULATION can reference a base version from which line items are copied
+- Plan versions are scoped to a company; versions from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each plan version is scoped to a Company via companyId (organization module)
+- **Self-referencing Base Version**: A plan version optionally references another PlanVersion via baseVersionId for copying line items

package/src/modules/accounting/docs/models/ProfitCenter.md

@@ -0,0 +1,66 @@
+# ProfitCenter
+
+## Description
+
+ProfitCenter represents a discrete business segment — such as a product line, regional division, or service line — for which management can independently evaluate profitability through internal profit and loss reporting. Each profit center carries a code, name, optional description, optional responsible person, company scope, validity period (valid-from/to), and a status following a lifecycle from DRAFT through ACTIVE to INACTIVE. Revenue and cost transactions posted in the finance-ledger are tagged with profit center assignments, enabling aggregation of income and expenses at the profit center level. Profit centers are organized into hierarchical groupings via ProfitCenterHierarchy and are deliberately decoupled from the organizational hierarchy to allow flexible, cross-cutting profitability views.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createProfitCenter
+    Draft --> Draft: updateProfitCenter
+    Draft --> Active: activateProfitCenter
+    Active --> Active: updateProfitCenter (limited fields)
+    Active --> Inactive: deactivateProfitCenter
+    Inactive --> Active: reactivateProfitCenter
+    Draft --> [*]: deleteProfitCenter
+```
+
+### Command Definitions
+
+- [createProfitCenter](../commands/CreateProfitCenter.md) - Create a new profit center in DRAFT status with code, name, and validity period
+- [updateProfitCenter](../commands/UpdateProfitCenter.md) - Update mutable fields of a profit center (name, description, responsible person)
+- [activateProfitCenter](../commands/ActivateProfitCenter.md) - Activate a DRAFT profit center, making it available for transaction tagging
+- [deactivateProfitCenter](../commands/DeactivateProfitCenter.md) - Deactivate an ACTIVE profit center, preventing new transaction assignments
+- [reactivateProfitCenter](../commands/ReactivateProfitCenter.md) - Reactivate an INACTIVE profit center back to ACTIVE status
+- [deleteProfitCenter](../commands/DeleteProfitCenter.md) - Delete a DRAFT profit center and its hierarchy assignment
+- [assignProfitCenterToHierarchyNode](../commands/AssignProfitCenterToHierarchyNode.md) - Assign or reassign a profit center to a hierarchy node
+
+### Query Definitions
+
+- [GetProfitCenter](../queries/GetProfitCenter.md) - Retrieve a profit center by id
+- [ListProfitCenters](../queries/ListProfitCenters.md) - List profit centers with filters (status, company, validity period)
+
+### Models
+
+- ProfitCenter
+
+### Invariants
+
+- Profit center can only be created in DRAFT status
+- Profit center requires a unique code within the company scope
+- Profit center requires a name
+- Profit center must reference a valid companyId; the company must be in ACTIVE status
+- Valid-from date is required; valid-to date is optional
+- Valid-to date, when specified, must be on or after the valid-from date
+- Profit center code cannot be changed after activation
+- Only DRAFT profit centers can be deleted; ACTIVE and INACTIVE profit centers cannot be deleted
+- Only ACTIVE profit centers within their validity period can receive transaction assignments
+- Transactions cannot be assigned to a DRAFT or INACTIVE profit center
+- Transactions cannot be assigned to a profit center outside its validity period (before valid-from or after valid-to)
+- Activating an already ACTIVE profit center fails with an invalid status transition error
+- Deactivating a DRAFT profit center fails with an invalid status transition error
+- Profit centers are scoped to a company; profit centers from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each profit center is scoped to a Company via companyId (organization module)
+- **References ProfitCenterHierarchyNode**: Each profit center can be assigned to a ProfitCenterHierarchyNode within a hierarchy
+- **References User**: Each profit center optionally references a responsible person via responsiblePersonId (user-management module)

package/src/modules/accounting/docs/models/ProfitCenterHierarchy.md

@@ -0,0 +1,36 @@
+# ProfitCenterHierarchy
+
+## Description
+
+ProfitCenterHierarchy is the organizational structure entity that defines a tree-based grouping of profit centers for hierarchical roll-up reporting and profitability aggregation. Each hierarchy carries a name and company scope. Profit center hierarchies support multi-dimensional analysis by business dimension such as region, product line, or service line, enabling both detailed drill-down analysis and executive-level summary reporting. Multiple hierarchies can coexist for the same company to support different analytical perspectives (e.g., one by region, one by product line).
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createProfitCenterHierarchy](../commands/CreateProfitCenterHierarchy.md) - Create a new profit center hierarchy with a name for a company
+
+### Query Definitions
+
+- [GetProfitCenterHierarchy](../queries/GetProfitCenterHierarchy.md) - Retrieve a profit center hierarchy by id with its full node tree
+
+### Models
+
+- ProfitCenterHierarchy
+- ProfitCenterHierarchyNode
+
+### Invariants
+
+- Profit center hierarchy requires a name
+- Profit center hierarchy must reference a valid companyId; the company must be in ACTIVE status
+- Profit center hierarchies are scoped to a company; hierarchies from different companies are fully isolated
+- Hierarchy roll-up aggregates financial results from child nodes up to parent nodes
+
+### Relationships
+
+- **References Company**: Each profit center hierarchy is scoped to a Company via companyId (organization module)
+- **Has Many ProfitCenterHierarchyNode**: A profit center hierarchy contains one or more hierarchy nodes forming a tree structure

package/src/modules/accounting/docs/models/ProfitCenterHierarchyAssignment.md

@@ -0,0 +1,36 @@
+# ProfitCenterHierarchyAssignment
+
+## Description
+
+ProfitCenterHierarchyAssignment represents the assignment of a profit center to a specific node within a profit center hierarchy. Each assignment links a profit center to exactly one node per hierarchy, enabling hierarchical roll-up reporting across multiple hierarchy dimensions simultaneously. A profit center can be assigned to nodes in multiple hierarchies, but within a given hierarchy it can only be assigned to one node at a time. Reassigning a profit center to a different node within the same hierarchy replaces the previous assignment.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignProfitCenterToHierarchyNode](../commands/AssignProfitCenterToHierarchyNode.md) - Assign a profit center to a hierarchy node, replacing any existing assignment within the same hierarchy
+
+### Query Definitions
+
+- [GetProfitCenterHierarchy](../queries/GetProfitCenterHierarchy.md) - Retrieve hierarchy nodes and their associated profit center assignments
+
+### Models
+
+- ProfitCenterHierarchyAssignment
+
+### Invariants
+
+- A profit center can be assigned to exactly one node within a given hierarchy (enforced by a unique index on profitCenterId and hierarchyId)
+- A profit center can be assigned to nodes in multiple different hierarchies simultaneously
+- Assigning a profit center to a new node within the same hierarchy replaces the previous assignment
+- Both the profit center and the target hierarchy node must exist before an assignment can be created
+
+### Relationships
+
+- **References ProfitCenter**: Each assignment references a ProfitCenter via profitCenterId
+- **References ProfitCenterHierarchy**: Each assignment references a ProfitCenterHierarchy via hierarchyId
+- **References ProfitCenterHierarchyNode**: Each assignment references a ProfitCenterHierarchyNode via hierarchyNodeId

package/src/modules/accounting/docs/models/ProfitCenterHierarchyNode.md

@@ -0,0 +1,39 @@
+# ProfitCenterHierarchyNode
+
+## Description
+
+ProfitCenterHierarchyNode represents a single node within a profit center hierarchy tree, supporting parent-child relationships that enable hierarchical roll-up of profitability results from leaf-level profit centers through intermediate grouping nodes to the root. Each node carries a name, optional parent node reference, hierarchy reference, sort order, and level attribute. Nodes serve as the assignment target for profit centers, allowing flexible grouping by business dimension such as region, product line, or service line.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createProfitCenterHierarchyNode](../commands/CreateProfitCenterHierarchyNode.md) - Create a new hierarchy node as a child of an existing node or as the root node
+- [deleteProfitCenterHierarchyNode](../commands/DeleteProfitCenterHierarchyNode.md) - Delete a hierarchy node that has no child nodes or assigned profit centers
+
+### Query Definitions
+
+- [GetProfitCenterHierarchy](../queries/GetProfitCenterHierarchy.md) - Retrieve hierarchy nodes as part of the full hierarchy tree
+
+### Models
+
+- ProfitCenterHierarchyNode
+
+### Invariants
+
+- Hierarchy node requires a name
+- Hierarchy node must belong to a valid ProfitCenterHierarchy via hierarchyId
+- A hierarchy node cannot be its own parent (no self-referencing)
+- A hierarchy node cannot create a circular reference (child cannot be an ancestor of its parent)
+- Removing a hierarchy node that has child nodes is rejected; children must be reassigned or removed first
+- Removing a hierarchy node that has profit centers assigned is rejected; profit centers must be reassigned first
+
+### Relationships
+
+- **Belongs to ProfitCenterHierarchy**: Each node belongs to a ProfitCenterHierarchy via hierarchyId
+- **Self-referencing Parent**: Each node optionally references a parent ProfitCenterHierarchyNode via parentNodeId
+- **Has Many ProfitCenter**: A hierarchy node can have multiple profit centers assigned to it

package/src/modules/accounting/docs/models/VarianceReport.md

@@ -0,0 +1,58 @@
+# VarianceReport
+
+## Description
+
+VarianceReport is the management accounting report entity that compares planned (budget) amounts against actual costs and revenues by cost object and accounting period. Each report carries a cost object type and id (polymorphic reference to cost center, profit center, or internal order), accounting period reference, company scope, summary totals (total planned, total actual, total variance), and a status following a DRAFT to FINAL lifecycle. Actual amounts are sourced from posted journal entries in the finance-ledger module, aggregated by cost element, period, and cost object. Planned amounts are sourced from BudgetLineItems in budget-management. Each report contains one or more VarianceReportLine child records that provide cost-element-level detail, enabling managers to diagnose which cost types are driving deviations.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: generateVarianceReport
+    Draft --> Final: finalizeVarianceReport
+```
+
+### Command Definitions
+
+- [generateVarianceReport](../commands/GenerateVarianceReport.md) - Generate a variance report in DRAFT status by collecting actuals and plan amounts, computing variances per cost element
+- [finalizeVarianceReport](../commands/FinalizeVarianceReport.md) - Finalize a DRAFT variance report, locking it for distribution to management
+
+### Query Definitions
+
+- [GetVarianceReport](../queries/GetVarianceReport.md) - Retrieve a variance report by id with all detail lines
+
+### Models
+
+- VarianceReport
+- VarianceReportLine
+
+### Invariants
+
+- Variance report can only be created in DRAFT status
+- Variance report must reference a valid companyId; the company must be in ACTIVE status
+- Variance report must reference a valid accounting period from finance-ledger
+- Variance report must reference a valid cost object (cost center, profit center, or internal order)
+- Variance report summary totals (total planned, total actual, total variance) are computed from the sum of its detail lines
+- Variance report can transition from DRAFT to FINAL
+- Variance report in FINAL status cannot be transitioned back to DRAFT
+- A FINAL variance report cannot be modified
+- A DRAFT variance report can be updated before finalization
+- A variance report cannot be generated if no budget line items exist for the specified cost object and period
+- Actual amounts are sourced exclusively from POSTED journal entries; DRAFT journal entries are excluded
+- Regenerating a variance report for the same cost object and period replaces the existing DRAFT report
+- A FINAL variance report is not overwritten by regeneration; a new DRAFT is created alongside it
+- Variance reports are scoped to a single company; data from other companies is excluded
+- Multiple variance reports can exist for the same cost object across different accounting periods
+
+### Relationships
+
+- **References Company**: Each variance report is scoped to a Company via companyId (organization module)
+- **References AccountingPeriod**: Each variance report references an AccountingPeriod via accountingPeriodId (finance-ledger module)
+- **Polymorphic Cost Object**: Each variance report references a cost object via costObjectType and costObjectId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **Has Many VarianceReportLine**: A variance report contains one or more variance report lines providing cost-element-level detail

package/src/modules/accounting/docs/models/VarianceReportLine.md

@@ -0,0 +1,43 @@
+# VarianceReportLine
+
+## Description
+
+VarianceReportLine is a child record of a VarianceReport that captures the planned amount, actual amount, computed variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE) for a specific cost element within a specific accounting period. Each line carries a variance report reference, cost element reference, accounting period reference, planned amount, actual amount, variance amount, variance percentage, and variance direction. Variance direction is determined by account type: for cost/expense elements, actual below plan is FAVORABLE; for revenue elements, actual above plan is FAVORABLE. This cost-element-level detail enables managers to diagnose exactly which cost types are driving deviations from the budget.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [generateVarianceReport](../commands/GenerateVarianceReport.md) - Variance report lines are created as part of generating a variance report
+
+### Query Definitions
+
+- [GetVarianceReport](../queries/GetVarianceReport.md) - Retrieve variance report lines as part of the parent variance report
+
+### Models
+
+- VarianceReportLine
+
+### Invariants
+
+- Variance report line must reference a valid variance report via varianceReportId
+- Variance report line must reference a valid cost element via costElementId
+- Variance report line must reference a valid accounting period via accountingPeriodId
+- Variance amount is calculated as actual amount minus planned amount
+- Variance percentage is calculated as (actual - planned) / planned * 100; division by zero is handled gracefully when planned amount is zero
+- For cost/expense cost elements, variance direction is FAVORABLE when actual is less than planned, UNFAVORABLE when actual is greater than planned
+- For revenue cost elements, variance direction is FAVORABLE when actual is greater than planned, UNFAVORABLE when actual is less than planned
+- When actual equals planned, variance amount is zero and variance direction is FAVORABLE
+- A variance report line is created for each cost element that has either a planned amount or an actual amount (or both)
+- A cost element with actual postings but no corresponding budget line item generates a detail line with zero planned amount
+- Variance report lines cannot be modified independently of the parent variance report
+
+### Relationships
+
+- **Belongs to VarianceReport**: Each variance report line belongs to a VarianceReport via varianceReportId
+- **References CostElement**: Each variance report line references a CostElement via costElementId
+- **References AccountingPeriod**: Each variance report line references an AccountingPeriod via accountingPeriodId (finance-ledger module)

package/src/modules/accounting/docs/queries/CalculateBudgetAvailability.md

@@ -0,0 +1,64 @@
+# CalculateBudgetAvailability
+
+## Overview
+
+CalculateBudgetAvailability computes the available budget for a given cost element, cost object, and accounting period using the formula: Available = Budget - (Actual + Commitments + Encumbrances). The budget amount is sourced from the matching BudgetLineItem in the ACTIVE budget for the cost object. Actual amounts are sourced from posted journal entries in the finance-ledger module. Commitment amounts are sourced from outstanding purchase order commitment records received from the purchase module. Encumbrances are reserved for future extension and treated as zero in the current implementation. This query is the foundation for budgetary control (funds check) and is invoked during transaction validation to prevent overspending.
+
+## Business Rules
+
+- Accepts required parameters: `{ costElementId, costObjectId, costObjectType, accountingPeriodId }`
+- Locates the ACTIVE budget matching the cost object and fiscal year containing the given accounting period
+- Retrieves the BudgetLineItem matching the cost element and accounting period
+- If no matching budget or line item exists, returns available as null with a flag indicating no budget is defined
+- Budget amount is the planned amount from the matching BudgetLineItem
+- Actual amount is the sum of posted journal entry line amounts matching the cost element, cost object, and accounting period
+- Commitment amount is the sum of outstanding purchase order commitment records matching the cost element, cost object, and accounting period
+- Encumbrance amount is zero (future extension placeholder)
+- Available = Budget - (Actual + Commitments + Encumbrances)
+- Returns the computed availability along with each component amount (budget, actual, commitments, encumbrances, available)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input: costElementId, costObjectId, costObjectType, accountingPeriodId] --> B[Find ACTIVE budget for cost object and fiscal year]
+    B --> C{ACTIVE budget found?}
+    C -->|No| D[Return null availability with NO_BUDGET_DEFINED flag]
+    C -->|Yes| E[Find BudgetLineItem matching cost element and period]
+    E --> F{Line item found?}
+    F -->|No| G[Return null availability with NO_BUDGET_LINE_ITEM flag]
+    F -->|Yes| H[Retrieve budget amount from line item]
+    H --> I[Sum actual amounts from posted journal entries]
+    I --> J[Sum commitment amounts from commitment records]
+    J --> K[Set encumbrance amount to zero]
+    K --> L[Compute Available = Budget - Actual + Commitments + Encumbrances]
+    L --> M[Return budget, actual, commitments, encumbrances, and available amounts]
+```
+
+## External Dependencies
+
+- [finance-ledger::listJournalEntries](../../../finance-ledger/docs/queries/ListJournalEntries.md) - Actual amounts sourced from posted journal entries
+
+## Error Scenarios
+
+- **NO_BUDGET_DEFINED**: No ACTIVE budget exists for the specified cost object and fiscal year — caller receives null availability
+- **NO_BUDGET_LINE_ITEM**: ACTIVE budget exists but no line item matches the specified cost element and period — caller receives null availability
+- **COST_ELEMENT_NOT_FOUND**: Provided costElementId does not reference an existing cost element
+- **COST_OBJECT_NOT_FOUND**: Provided costObjectId does not reference an existing cost object of the specified type
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Provided accountingPeriodId does not reference an existing accounting period
+
+## Test Cases
+
+- returns error when cost element does not exist
+- returns error when cost object does not exist
+- returns error when accounting period does not exist
+- returns budget availability with all component amounts when budget and line item exist
+- computes available as budget minus actual plus commitments plus encumbrances
+- returns actual amount aggregated from posted journal entries only
+- excludes draft journal entries from actual amount calculation
+- returns commitment amount from outstanding purchase order records
+- returns encumbrance amount as zero
+- returns null availability with NO_BUDGET_DEFINED flag when no active budget exists
+- returns null availability with NO_BUDGET_LINE_ITEM flag when line item does not exist for cost element and period
+- handles zero budget amount gracefully
+- handles case where actual exceeds budget resulting in negative availability

package/src/modules/accounting/docs/queries/GetAllocationCycle.md

@@ -0,0 +1,43 @@
+# GetAllocationCycle
+
+## Overview
+
+GetAllocationCycle retrieves a single allocation cycle record by id, returning all header fields (name, type, status, company reference, accounting period reference) along with all associated allocation rules (sender cost center, receiver cost objects, percentages) and allocation results (sender, receiver, allocated amount, cost element). This is the primary query for reviewing allocation cycle configuration, verifying test run results, and auditing posted allocations.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full allocation cycle record including all header fields
+- Includes all associated allocation rules with sender, receiver, and percentage details
+- Includes all allocation results if the cycle has been executed (EXECUTED, POSTED, or REVERSED status)
+- Allocation results are immutable records created during execution
+- Returns null if no matching allocation cycle is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from AllocationCycle where id = input.id]
+    B --> C{Allocation cycle found?}
+    C -->|Yes| D[Load all associated allocation rules]
+    D --> E[Load all associated allocation results]
+    E --> F[Return allocation cycle with rules and results]
+    C -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: No allocation cycle matches the given id — caller receives null
+
+## Test Cases
+
+- returns allocation cycle with all fields and allocation rules when found by id
+- returns allocation cycle with allocation results when cycle has been executed
+- returns allocation cycle with empty results when cycle is in DRAFT or VALIDATED status
+- returns allocation rules with sender, receiver, and percentage details
+- returns null when no allocation cycle matches the given id

package/src/modules/accounting/docs/queries/GetBudget.md

@@ -0,0 +1,42 @@
+# GetBudget
+
+## Overview
+
+GetBudget retrieves a single budget record by id, returning all header fields (name, budget holder, fiscal year reference, cost object reference, cost object type, status, plan version type, total amount) along with all associated budget line items. Each line item includes the cost element reference, accounting period reference, planned amount, and the GL account derived from the primary cost element's mapping. This is the primary query for viewing budget details, reviewing planned amounts by cost element and period, and supporting budget vs. actual comparison workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full budget record including all header fields
+- Includes all associated BudgetLineItem records
+- Each line item includes cost element reference, accounting period reference, planned amount, and derived GL account
+- The GL account on each line item is derived from the referenced primary cost element's GL account mapping
+- Returns null if no matching budget is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from Budget where id = input.id]
+    B --> C{Budget found?}
+    C -->|Yes| D[Load all associated BudgetLineItem records]
+    D --> E[Return budget with all line items]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: No budget matches the given id — caller receives null
+
+## Test Cases
+
+- returns budget with all header fields and line items when found by id
+- returns budget line items with cost element, period, and planned amount
+- returns budget line items with derived GL account from cost element mapping
+- returns budget with empty line items when budget has no line items
+- returns null when no budget matches the given id

package/src/modules/accounting/docs/queries/GetCostCenter.md

@@ -0,0 +1,38 @@
+# GetCostCenter
+
+## Overview
+
+GetCostCenter retrieves a single cost center record by id, including all master data fields (code, name, description, category, responsible person, department reference, validity period) and the hierarchy node assignment within the cost center hierarchy. This is the primary query for viewing cost center details, validating cost center configuration, and supporting cost posting, budget, and allocation workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full cost center record including all master data fields
+- Includes the hierarchy node assignment (node id and hierarchy reference) for the cost center
+- Returns null if no matching cost center is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from CostCenter where id = input.id]
+    B --> C{Cost center found?}
+    C -->|Yes| D[Load hierarchy node assignment]
+    D --> E[Return cost center with hierarchy node]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: No cost center matches the given id — caller receives null
+
+## Test Cases
+
+- returns cost center with all fields and hierarchy node assignment when found by id
+- returns cost center with responsible person and department reference populated
+- returns null when no cost center matches the given id