@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/accounting/docs/features/variance-analysis.md

@@ -0,0 +1,130 @@
+# Variance Analysis
+
+## Overview
+
+Variance Analysis is the management accounting capability of the accounting module that compares planned (budget) amounts against actual costs and revenues by cost object and accounting period. A VarianceReport entity captures the cost object reference (cost center, profit center, or internal order), the accounting period, report status (DRAFT or FINAL), and summary totals (total planned, total actual, total variance). Each VarianceReport contains one or more VarianceReportLine child records, each keyed by cost element and accounting period, that capture the planned amount, actual amount, computed variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE). This cost-element-level detail enables managers to diagnose which cost types are driving deviations rather than only seeing aggregate totals. 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 the budget-management module, which use cost elements as their planning axis.
+
+The feature follows a five-step workflow: collect actuals from posted journal entries, collect plan amounts from budget line items, calculate variance per cost element as the difference between actual and planned, categorize the variance direction based on account type, and generate a management report with detail lines. Variance reports are scoped to a Company and reference a specific AccountingPeriod. Reports can be generated at the individual cost object level or aggregated up cost center and profit center hierarchies. Variance analysis typically runs as a period-end process after all postings for the period are complete. Detailed variance categorization (input price, input quantity, volume, mix) and manufacturing-specific variances (price, usage, efficiency) are out of scope for this feature.
+
+## Business Purpose
+
+Organizations need systematic variance analysis to monitor financial performance against plans and enable timely corrective action:
+
+- **Budget adherence monitoring**: Comparing actual costs and revenues against budgeted amounts by cost object reveals where spending is on track and where deviations require management attention
+- **Favorable/unfavorable categorization**: Automatically classifying variances as favorable (actual costs below plan, or actual revenue above plan) or unfavorable (the inverse) provides immediate directional context for decision-makers without manual interpretation
+- **Cost element detail**: VarianceReportLine records break down variances by cost element (salaries, travel, materials, etc.) within each cost object, enabling managers to identify exactly which cost type is driving deviations rather than only seeing an aggregate total — this is essential for actionable root-cause analysis
+- **Cost object granularity**: Generating variance reports per cost center, profit center, or internal order allows managers to pinpoint exactly which organizational unit or project is driving deviations from plan
+- **Hierarchy aggregation**: Rolling up variances along cost center and profit center hierarchies enables both detailed drill-down analysis and executive-level summary reporting in a single feature
+- **Period-end management reporting**: Running variance analysis after all period postings are complete produces accurate, comprehensive reports that inform budget revisions, resource reallocation, and strategic decisions for subsequent periods
+- **Variance quantification**: Calculating both absolute variance amounts and variance percentages allows managers to assess deviations in context — a large absolute variance on a small budget line signals a different issue than the same amount on a large budget line
+- **Draft-to-final lifecycle**: The DRAFT to FINAL status progression allows controllers to review and validate variance reports before distributing them to management, preventing premature or incorrect reporting
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> CollectActuals: initiateVarianceAnalysis
+    CollectActuals --> CollectPlan: actuals aggregated
+    CollectPlan --> CalculateVariance: plan amounts retrieved
+    CalculateVariance --> Categorize: variance computed
+    Categorize --> GenerateReport: direction assigned
+    GenerateReport --> [*]: VarianceReport created (DRAFT)
+```
+
+```mermaid
+flowchart TD
+    A[Period-end: all postings complete] --> B[Collect actual amounts from posted journal entries]
+    B --> C[Aggregate actuals by cost element + cost object + period]
+    C --> D[Collect planned amounts from budget-management BudgetLineItems by cost element]
+    D --> E[Match actuals to plan by cost element, cost object, and period]
+    E --> F[Calculate variance per cost element: Actual - Planned]
+    F --> G{Account type?}
+    G -- Cost/Expense --> H{Actual < Planned?}
+    H -- Yes --> I[FAVORABLE]
+    H -- No --> J[UNFAVORABLE]
+    G -- Revenue --> K{Actual > Planned?}
+    K -- Yes --> L[FAVORABLE]
+    K -- No --> M[UNFAVORABLE]
+    I --> N[Compute variance percentage]
+    J --> N
+    L --> N
+    M --> N
+    N --> O[Create VarianceReportLine per cost element]
+    O --> O2[Create VarianceReport in DRAFT with summary totals and detail lines]
+    O2 --> P{Review and validate}
+    P -- Approved --> Q[Finalize report: status FINAL]
+    P -- Issues found --> R[Investigate and correct source data]
+    R --> A
+```
+
+```mermaid
+flowchart TD
+    A[Select reporting scope] --> B{Report level?}
+    B -- Individual cost object --> C[Generate report for single cost center / profit center / internal order]
+    B -- Hierarchy --> D[Retrieve child cost objects from hierarchy]
+    D --> E[Generate individual reports per child]
+    E --> F[Aggregate variances up hierarchy levels]
+    F --> G[Produce consolidated hierarchy report]
+    C --> H[VarianceReport ready for review]
+    G --> H
+```
+
+## Scenario Patterns
+
+- **Monthly cost center review**: At month-end close, the controller initiates variance analysis for all cost centers within a company for the current accounting period. The system collects posted journal entry totals by cost center, retrieves corresponding budget line items, computes variances, and generates DRAFT variance reports. The controller reviews and finalizes each report before distributing to cost center managers
+- **Profit center profitability check**: A division head requests a variance report for their profit center to compare actual revenue and costs against the annual plan. The report's detail lines show revenue above plan (FAVORABLE) but the material cost element significantly above plan (UNFAVORABLE), enabling the manager to pinpoint supplier pricing changes as the root cause without needing a separate drill-down report
+- **Internal order cost overrun detection**: A project manager reviews the variance report for an internal order representing a capital project. The report reveals actual spending at 120% of the planned amount with two periods remaining, triggering a budget revision request and scope review
+- **Hierarchy roll-up for executive reporting**: The CFO requests a consolidated variance report across all profit centers. The system generates individual profit center variance reports and then aggregates them up the profit center hierarchy, producing a company-level summary showing total planned vs. actual with net variance amounts and percentages
+- **Cross-period trend analysis**: A controller generates variance reports for the same cost center across multiple consecutive periods to identify whether an unfavorable variance is a one-time event or a recurring trend, informing whether a structural budget adjustment is needed
+- **Revenue variance investigation**: A sales manager receives a variance report showing actual revenue below plan (UNFAVORABLE) for their profit center. The variance percentage of -15% triggers a review of sales pipeline and customer order patterns to understand the shortfall
+- **Period-end sequential processing**: The accounting team completes all journal entry postings and subledger reconciliations for the period, then runs variance analysis as the final step before period close. This sequence ensures variance reports reflect the complete and accurate financial picture for the period
+
+## Test Cases
+
+- Variance report can only be created for a valid Company that is in ACTIVE status
+- Variance report must reference a valid AccountingPeriod
+- Variance report must reference a valid cost object (cost center, profit center, or internal order)
+- Variance report is created in DRAFT status
+- Variance report can transition from DRAFT to FINAL
+- Variance report in FINAL status cannot be transitioned back to DRAFT
+- A VarianceReport contains one or more VarianceReportLine child records, each keyed by cost element and accounting period
+- Each VarianceReportLine records: cost element reference, accounting period, planned amount, actual amount, variance amount, variance percentage, and variance direction
+- VarianceReport summary totals (total planned, total actual, total variance) are computed from the sum of its detail lines
+- Variance amount on each VarianceReportLine is calculated as actual amount minus planned amount
+- Variance percentage on each VarianceReportLine is calculated as (actual - planned) / planned * 100
+- When planned amount is zero and actual amount is non-zero on a detail line, variance percentage is handled gracefully (not division by zero)
+- For cost/expense cost elements, variance direction is FAVORABLE when actual amount is less than planned amount
+- For cost/expense cost elements, variance direction is UNFAVORABLE when actual amount is greater than planned amount
+- For revenue cost elements, variance direction is FAVORABLE when actual amount is greater than planned amount
+- For revenue cost elements, variance direction is UNFAVORABLE when actual amount is less than planned amount
+- When actual equals planned on a detail line, variance amount is zero and variance direction is FAVORABLE
+- Actual amounts are sourced exclusively from POSTED journal entries in the finance-ledger module
+- DRAFT journal entries are excluded from actual amount aggregation
+- Actual amounts are aggregated by cost element, cost object, and accounting period
+- Planned amounts are sourced from BudgetLineItems in the budget-management module, matched by cost element
+- A variance report cannot be generated if no budget line items exist for the specified cost object and period
+- A VarianceReportLine 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 reports for cost centers aggregate all journal lines assigned to that cost center in the given period, grouped by cost element
+- Variance reports for profit centers aggregate all journal lines assigned to that profit center in the given period, grouped by cost element
+- Variance reports for internal orders aggregate all journal lines assigned to that internal order in the given period, grouped by cost element
+- Hierarchy aggregation for cost centers sums child cost center variances into the parent cost center report
+- Hierarchy aggregation for profit centers sums child profit center variances into the parent profit center report
+- Hierarchy-aggregated reports include both the individual child variances and the consolidated parent totals
+- A DRAFT variance report can be updated (e.g., to correct a cost object reference) before finalization
+- A FINAL variance report cannot be modified
+- Generating a variance report for a period with no posted journal entries results in zero actual amounts
+- 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
+- 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 if source data changes
+- Variance report includes both the absolute variance amount and the variance percentage
+- Variance report records the variance direction as either FAVORABLE or UNFAVORABLE
+
+## Reference Links
+
+- [SAP S/4HANA Variance Analysis in Controlling](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/b33fa239f4d446e9a6c8a585c4e148c8.html)
+- [Oracle Fusion Budgetary Control and Variance Reporting](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/budgetary-control.html)
+- [Odoo Budget Management and Analysis](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/budget.html)
+- [NetSuite Budget vs. Actual Reporting](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1584498.html)
+- [CIMA Management Accounting Variance Analysis](https://www.cimaglobal.com/resources/)

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

@@ -0,0 +1,81 @@
+# AllocationCycle
+
+## Description
+
+AllocationCycle is the controlling entity that groups a set of allocation rules for distributing overhead costs from sender cost centers to receiver cost objects (cost centers, profit centers, or internal orders). Each cycle carries a name, allocation type (ASSESSMENT or DISTRIBUTION), company scope, accounting period reference, and a status. Assessment-type allocations post using secondary cost elements, aggregating original cost elements into a single overhead category on the receiver. Distribution-type allocations preserve the original primary cost elements on the receiver side for full cost transparency. Allocation cycles progress through a controlled lifecycle — DRAFT, VALIDATED, EXECUTED, POSTED, and optionally REVERSED — ensuring allocations are reviewed and tested before affecting the general ledger.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAllocationCycle
+    Draft --> Draft: updateAllocationCycle / createAllocationRule / deleteAllocationRule
+    Draft --> Validated: validateAllocationCycle
+    Validated --> Draft: invalidateAllocationCycle
+    Validated --> Executed: executeAllocationCycle (ACTUAL)
+    Executed --> Posted: postAllocationCycle
+    Posted --> Reversed: reverseAllocationCycle
+    Draft --> [*]: deleteAllocationCycle
+```
+
+### Command Definitions
+
+- [createAllocationCycle](../commands/CreateAllocationCycle.md) - Create a new allocation cycle in DRAFT status with type, name, company, and accounting period
+- [updateAllocationCycle](../commands/UpdateAllocationCycle.md) - Update mutable fields of a DRAFT allocation cycle (name)
+- [validateAllocationCycle](../commands/ValidateAllocationCycle.md) - Validate a DRAFT cycle, verifying all rules have percentages summing to 100% per sender
+- [invalidateAllocationCycle](../commands/InvalidateAllocationCycle.md) - Return a VALIDATED cycle to DRAFT for further editing
+- [executeAllocationCycle](../commands/ExecuteAllocationCycle.md) - Execute a VALIDATED cycle in ACTUAL mode, creating immutable allocation result records
+- [postAllocationCycle](../commands/PostAllocationCycle.md) - Post an EXECUTED cycle, creating journal entries through finance-ledger subledger integration
+- [reverseAllocationCycle](../commands/ReverseAllocationCycle.md) - Reverse a POSTED cycle by creating reversal journal entries with inverted amounts
+- [deleteAllocationCycle](../commands/DeleteAllocationCycle.md) - Delete a DRAFT allocation cycle and its associated rules
+- [createAllocationRule](../commands/CreateAllocationRule.md) - Add an allocation rule to a DRAFT cycle defining sender, receiver, and percentage
+- [deleteAllocationRule](../commands/DeleteAllocationRule.md) - Remove an allocation rule from a DRAFT cycle
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve an allocation cycle by id with its rules and results
+- [ListAllocationCycles](../queries/ListAllocationCycles.md) - List allocation cycles with filters (type, status, company, period)
+
+### Models
+
+- AllocationCycle
+- AllocationRule
+- AllocationResult
+
+### Invariants
+
+- Allocation cycle can only be created in DRAFT status
+- Allocation cycle requires a valid type (ASSESSMENT or DISTRIBUTION)
+- Allocation cycle requires a valid name
+- Allocation cycle must reference a valid companyId; the company must be in ACTIVE status
+- Allocation cycle must reference a valid accounting period
+- Allocation rules can only be added to or removed from a DRAFT cycle
+- Allocation rule percentages for a given sender must sum to exactly 100%
+- Allocation rule percentage values must be positive (greater than zero)
+- A sender cost center cannot also appear as a receiver within the same allocation rule set
+- Validating a cycle with no allocation rules fails
+- A VALIDATED cycle can be returned to DRAFT for further editing
+- Executing a cycle that is not in VALIDATED status fails
+- Execution in ACTUAL mode creates immutable AllocationResult records
+- Posting transitions the cycle from EXECUTED to POSTED, creating journal entries
+- Assessment-type allocation postings use secondary cost elements in the generated journal entries
+- Distribution-type allocation postings preserve the original primary cost elements in the generated journal entries
+- Posting an allocation cycle to a CLOSED or PERMANENTLY_CLOSED period is rejected
+- Reversing a POSTED cycle creates reversal journal entries with inverted amounts
+- A REVERSED cycle cannot be reversed again
+- Updating allocation cycle fields is only permitted while in DRAFT status
+- Deleting an allocation cycle is only permitted while in DRAFT status
+- Allocation cycles are scoped to a company; cycles from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each allocation cycle is scoped to a Company via companyId (organization module)
+- **References AccountingPeriod**: Each allocation cycle references an AccountingPeriod via accountingPeriodId (finance-ledger module)
+- **Has Many AllocationRule**: An allocation cycle contains one or more allocation rules defining sender-receiver-percentage mappings
+- **Has Many AllocationResult**: An executed allocation cycle produces immutable allocation result records

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

@@ -0,0 +1,37 @@
+# AllocationResult
+
+## Description
+
+AllocationResult is an immutable record produced when an allocation cycle is executed in ACTUAL mode, capturing the outcome of a single sender-receiver cost distribution. Each result carries an allocation cycle reference, sender cost center reference, receiver type, receiver id, allocated amount, and cost element reference. Allocation results serve as the authoritative audit trail for cost allocations, linking the cycle, sender, receiver, allocated amount, and cost element used. Once created, allocation result records cannot be modified or deleted — corrections are handled exclusively through cycle reversal and re-execution.
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [executeAllocationCycle](../commands/ExecuteAllocationCycle.md) - Allocation results are created as part of executing an allocation cycle in ACTUAL mode
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve allocation results as part of the parent allocation cycle
+
+### Models
+
+- AllocationResult
+
+### Invariants
+
+- Allocation results are created exclusively during allocation cycle execution in ACTUAL mode
+- Allocation results cannot be modified or deleted after creation
+- Each allocation result references the allocation cycle, sender, receiver, allocated amount, and cost element used
+- Allocation results serve as the immutable audit trail for cost allocations
+
+### Relationships
+
+- **Belongs to AllocationCycle**: Each allocation result belongs to an AllocationCycle via allocationCycleId
+- **References CostCenter (sender)**: Each allocation result references a sender CostCenter via senderCostCenterId
+- **Polymorphic Receiver**: Each allocation result references a receiver via receiverType and receiverId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **References CostElement**: Each allocation result references a CostElement via costElementId

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

@@ -0,0 +1,41 @@
+# AllocationRule
+
+## Description
+
+AllocationRule defines a single sender-receiver-percentage mapping within an allocation cycle, specifying which cost center sends costs, which cost object receives them, and the allocation percentage. Each rule carries an allocation cycle reference, sender cost center reference, receiver type, receiver id, and percentage. Receivers can be cost centers, profit centers, or internal orders (polymorphic reference). Multiple rules within a cycle define how a sender's costs are split across multiple receivers, with the constraint that percentages for a given sender must sum to exactly 100%.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createAllocationRule](../commands/CreateAllocationRule.md) - Add an allocation rule to a DRAFT allocation cycle
+- [deleteAllocationRule](../commands/DeleteAllocationRule.md) - Remove an allocation rule from a DRAFT allocation cycle
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve allocation rules as part of the parent allocation cycle
+
+### Models
+
+- AllocationRule
+
+### Invariants
+
+- Allocation rule must reference a valid allocation cycle via allocationCycleId
+- Allocation rule can only be added to or removed from a DRAFT allocation cycle
+- Allocation rule must reference a valid sender cost center
+- Allocation rule must reference a valid receiver cost object (cost center, profit center, or internal order)
+- A sender cost center cannot also appear as a receiver within the same allocation rule set
+- Allocation rule percentage must be a positive value (greater than zero)
+- Allocation rule percentages for a given sender must sum to exactly 100% across all rules in the cycle
+- Allocation rules cannot be modified after the cycle leaves DRAFT status
+
+### Relationships
+
+- **Belongs to AllocationCycle**: Each allocation rule belongs to an AllocationCycle via allocationCycleId
+- **References CostCenter (sender)**: Each allocation rule references a sender CostCenter via senderCostCenterId
+- **Polymorphic Receiver**: Each allocation rule references a receiver via receiverType and receiverId, which can be a CostCenter, ProfitCenter, or InternalOrder

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

@@ -0,0 +1,77 @@
+# Budget
+
+## Description
+
+Budget is the financial planning entity of the accounting module, enabling organizations to create budgets with line items per cost element, manage approval workflows, track multiple budget versions, and compare budgeted amounts against actual postings from finance-ledger. Each budget carries a name, optional description, budget holder, fiscal year reference, company scope, cost object type and id (polymorphic reference to cost center, profit center, or internal order), plan version reference, total amount, and status. Budgets follow a five-stage lifecycle — DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED — enforcing segregation of duties between budget creation, approval, and cost posting. When active, budgets enable budgetary control (funds check) that validates transactions against available budget using the formula: Available = Budget - (Actual + Commitments + Encumbrances).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createBudget
+    Draft --> Draft: updateBudget / createBudgetLineItem / deleteBudgetLineItem
+    Draft --> Submitted: submitBudget
+    Submitted --> Approved: approveBudget
+    Submitted --> Draft: rejectBudget
+    Approved --> Active: activateBudget
+    Active --> Closed: closeBudget
+    Draft --> [*]: deleteBudget
+```
+
+### Command Definitions
+
+- [createBudget](../commands/CreateBudget.md) - Create a new budget in DRAFT status with name, budget holder, fiscal year, cost object, and plan version
+- [updateBudget](../commands/UpdateBudget.md) - Update mutable fields of a DRAFT budget (name, description, budget holder)
+- [submitBudget](../commands/SubmitBudget.md) - Submit a DRAFT budget for approval review
+- [approveBudget](../commands/ApproveBudget.md) - Approve a SUBMITTED budget, advancing it toward activation
+- [rejectBudget](../commands/RejectBudget.md) - Reject a SUBMITTED budget back to DRAFT with a rejection reason
+- [activateBudget](../commands/ActivateBudget.md) - Activate an APPROVED budget, enabling budgetary control (funds check)
+- [closeBudget](../commands/CloseBudget.md) - Close an ACTIVE budget, preventing further modifications
+- [deleteBudget](../commands/DeleteBudget.md) - Delete a DRAFT budget and all associated line items
+- [createBudgetLineItem](../commands/CreateBudgetLineItem.md) - Add a budget line item to a DRAFT budget specifying cost element, period, and planned amount
+- [deleteBudgetLineItem](../commands/DeleteBudgetLineItem.md) - Remove a budget line item from a DRAFT budget
+
+### Query Definitions
+
+- [GetBudget](../queries/GetBudget.md) - Retrieve a budget by id with all line items
+- [ListBudgets](../queries/ListBudgets.md) - List budgets with filters (status, company, fiscal year, cost object)
+- [CalculateBudgetAvailability](../queries/CalculateBudgetAvailability.md) - Compute budget availability as Budget - (Actual + Commitments + Encumbrances) for a cost element, period, and cost object
+
+### Models
+
+- Budget
+- BudgetLineItem
+
+### Invariants
+
+- Budget can only be created in DRAFT status
+- Budget requires a valid companyId; the company must be in ACTIVE status
+- Budget requires a valid fiscal year reference from finance-ledger
+- Budget requires a name, budget holder, and cost object reference (cost center, profit center, or internal order)
+- Budget must reference a valid PlanVersion (BUDGET, FORECAST, or SIMULATION)
+- A budget with no line items cannot be submitted
+- Only a user different from the budget creator can approve the budget (segregation of duties)
+- Rejection requires a reason text
+- Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year
+- Multiple FORECAST or SIMULATION versions can coexist for the same cost object and fiscal year
+- Line items can only be added to or removed from a DRAFT budget
+- A CLOSED budget cannot be reopened; no further modifications are permitted
+- Funds check computes BudgetAvailability as Budget - (Actual + Commitments + Encumbrances) for the target cost element, period, and cost object
+- A transaction that exceeds BudgetAvailability is rejected with a budget exceeded error when budgetary control is active
+- Budget periods align with finance-ledger AccountingPeriod boundaries; misaligned periods are rejected
+- Locking a budget period prevents further modifications to planned amounts for that period
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each budget is scoped to a Company via companyId (organization module)
+- **References FiscalYear**: Each budget references a FiscalYear via fiscalYearId (finance-ledger module)
+- **References PlanVersion**: Each budget references a PlanVersion via planVersionId
+- **Polymorphic Cost Object**: Each budget references a cost object via costObjectType and costObjectId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **Has Many BudgetLineItem**: A budget contains one or more budget line items specifying planned amounts per cost element and period

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

@@ -0,0 +1,40 @@
+# BudgetLineItem
+
+## Description
+
+BudgetLineItem is a child record of a Budget that specifies the planned spending amount for a specific cost element within a specific accounting period. Each line item carries a budget reference, cost element reference, accounting period reference, and planned amount. The corresponding GL account for each line item is derived automatically from the referenced primary cost element's one-to-one GL account mapping defined in cost-element-management, ensuring a single authoritative planning axis while preserving traceability to the general ledger. Budget line items provide the granular cost-element-level detail needed for funds checking, budget-vs-actual comparison, and variance analysis.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createBudgetLineItem](../commands/CreateBudgetLineItem.md) - Add a budget line item to a DRAFT budget specifying cost element, period, and planned amount
+- [deleteBudgetLineItem](../commands/DeleteBudgetLineItem.md) - Remove a budget line item from a DRAFT budget
+
+### Query Definitions
+
+- [GetBudget](../queries/GetBudget.md) - Retrieve budget line items as part of the parent budget
+
+### Models
+
+- BudgetLineItem
+
+### Invariants
+
+- Budget line item must reference a valid budget via budgetId
+- Budget line item can only be added to or removed from a DRAFT budget
+- Budget line item requires a valid cost element reference; the cost element must be a PRIMARY type in ACTIVE status
+- Budget line item derives its GL account automatically from the referenced primary cost element's GL account mapping
+- Budget line item requires a valid accounting period reference from finance-ledger
+- Budget line item planned amount must be a positive value
+- Duplicate line items (same cost element and period) within a single budget are rejected
+
+### Relationships
+
+- **Belongs to Budget**: Each budget line item belongs to a Budget via budgetId
+- **References CostElement**: Each budget line item references a CostElement via costElementId
+- **References AccountingPeriod**: Each budget line item references an AccountingPeriod via accountingPeriodId (finance-ledger module)

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

@@ -0,0 +1,45 @@
+# Commitment
+
+## Description
+
+Commitment represents an outstanding purchase order amount that reduces available budget before the actual expense is incurred. Each commitment carries a cost element reference, cost object type and id (polymorphic reference to cost center, profit center, or internal order), accounting period reference, amount, purchase order reference, company scope, and status. Commitments are recorded when the purchase module confirms a purchase order, consumed when goods are received or invoices are matched (reducing the commitment and increasing actuals), and released when a purchase order is cancelled. Commitments are a key component of the budgetary control formula: Available = Budget - (Actual + Commitments + Encumbrances).
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [recordCommitment](../commands/RecordCommitment.md) - Record a commitment amount when a purchase order confirmation event is received
+- [consumeCommitment](../commands/ConsumeCommitment.md) - Reduce commitment and increase actual when goods receipt or invoice match event is received
+- [releaseCommitment](../commands/ReleaseCommitment.md) - Release commitment amount back to available budget when a purchase order is cancelled
+
+### Query Definitions
+
+- [GetBudget](../queries/GetBudget.md) - Commitment amounts are included in budget availability calculations
+
+### Models
+
+- Commitment
+
+### Invariants
+
+- Commitment must reference a valid cost element via costElementId
+- Commitment must reference a valid cost object via costObjectType and costObjectId (cost center, profit center, or internal order)
+- Commitment must reference a valid accounting period from finance-ledger
+- Commitment amount must be a positive value when recorded
+- Commitment must reference a valid purchase order via purchaseOrderId
+- Commitment must reference a valid companyId; the company must be in ACTIVE status
+- Commitment amounts are reduced and actual amounts are increased when a goods receipt or invoice match event is received
+- Commitment amounts are fully released when a purchase order cancellation event is received
+- Commitments reduce available budget in the budgetary control formula
+
+### Relationships
+
+- **References CostElement**: Each commitment references a CostElement via costElementId
+- **Polymorphic Cost Object**: Each commitment references a cost object via costObjectType and costObjectId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **References AccountingPeriod**: Each commitment references an AccountingPeriod via accountingPeriodId (finance-ledger module)
+- **References PurchaseOrder**: Each commitment references a PurchaseOrder via purchaseOrderId (purchase module)
+- **References Company**: Each commitment is scoped to a Company via companyId (organization module)

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

@@ -0,0 +1,51 @@
+# CostCenter
+
+## Description
+
+CostCenter represents a responsibility area within a company that accumulates overhead costs, such as an IT department, a production floor, or a facilities group. Each cost center carries a code, name, optional description, category (e.g., overhead, production, administration, sales, research), optional responsible person, optional department reference, company scope, validity period (valid-from/to dates), and a position within a cost center hierarchy via its hierarchy node assignment. Cost centers are distinct from organizational departments and serve as the primary receiver for overhead costs, acting as the foundational cost object referenced by cost allocation, budget management, variance analysis, and internal order settlement. Cost centers use validity-based lifecycle management rather than explicit status transitions.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createCostCenter](../commands/CreateCostCenter.md) - Create a new cost center with code, name, category, validity period, and hierarchy node assignment
+- [updateCostCenter](../commands/UpdateCostCenter.md) - Update mutable fields of a cost center (name, description, category, responsible person, department)
+- [deleteCostCenter](../commands/DeleteCostCenter.md) - Delete a cost center that has no dependent records (postings, budgets, allocation rules)
+- [assignCostCenterToHierarchyNode](../commands/AssignCostCenterToHierarchyNode.md) - Assign or reassign a cost center to a different hierarchy node within the same company
+
+### Query Definitions
+
+- [GetCostCenter](../queries/GetCostCenter.md) - Retrieve a cost center by id
+- [ListCostCenters](../queries/ListCostCenters.md) - List cost centers with filters (category, company, validity period)
+
+### Models
+
+- CostCenter
+
+### Invariants
+
+- Cost center requires a unique code within the company scope
+- Cost center code cannot be changed after creation to preserve referential integrity
+- Cost center requires a name and a valid category (overhead, production, administration, sales, research)
+- Cost center must reference a valid companyId; the company must be in ACTIVE status
+- Cost center must reference a valid hierarchy node within the same company's hierarchy
+- Cost center valid-from date must be earlier than or equal to valid-to date when both are provided
+- A cost center with no valid-to date is treated as indefinitely active from its valid-from date
+- A cost center whose valid-to date has passed cannot receive new cost postings
+- A cost center whose valid-from date is in the future cannot receive cost postings until that date is reached
+- A cost center cannot be deleted if it has associated cost postings, budget line items, or allocation rules referencing it
+- A cost center can only be assigned to a hierarchy node within the same company's hierarchy
+- Multiple cost centers can be assigned to the same hierarchy node
+- Changing a cost center's category is permitted and emits an audit event
+- Cost centers are scoped to a company; cost centers from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each cost center is scoped to a Company via companyId (organization module)
+- **References CostCenterHierarchyNode**: Each cost center is assigned to a CostCenterHierarchyNode via hierarchyNodeId
+- **References User**: Each cost center optionally references a responsible person via responsiblePersonId (user-management module)
+- **References Department**: Each cost center optionally references a Department via departmentId (organization module)

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

@@ -0,0 +1,38 @@
+# CostCenterHierarchy
+
+## Description
+
+CostCenterHierarchy is the organizational structure entity that defines a tree-based grouping of cost centers for hierarchical roll-up reporting and cost aggregation. Each hierarchy carries a name, version identifier, and company scope. A hierarchy must be established before any cost centers can be created within a company, following the SAP CO pattern where a hierarchy root is a prerequisite for cost center master data. Multiple hierarchy versions can exist within the same company to support current and planned organizational structures.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createCostCenterHierarchy](../commands/CreateCostCenterHierarchy.md) - Create a new cost center hierarchy with a name and version for a company
+
+### Query Definitions
+
+- [GetCostCenterHierarchy](../queries/GetCostCenterHierarchy.md) - Retrieve a cost center hierarchy by id with its full node tree
+
+### Models
+
+- CostCenterHierarchy
+- CostCenterHierarchyNode
+
+### Invariants
+
+- Cost center hierarchy requires a name and version identifier
+- Cost center hierarchy must reference a valid companyId; the company must be in ACTIVE status
+- Cost center hierarchy is scoped to a company; hierarchies from different companies are fully isolated
+- A cost center hierarchy can have multiple versions within the same company
+- A hierarchy root node must be established before child nodes can be added
+- Hierarchy roll-up reporting aggregates costs from child nodes up through parent nodes to the root
+
+### Relationships
+
+- **References Company**: Each cost center hierarchy is scoped to a Company via companyId (organization module)
+- **Has Many CostCenterHierarchyNode**: A cost center hierarchy contains one or more hierarchy nodes forming a tree structure

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

@@ -0,0 +1,41 @@
+# CostCenterHierarchyNode
+
+## Description
+
+CostCenterHierarchyNode represents a single node within a cost center hierarchy tree, supporting parent-child relationships that enable hierarchical roll-up of costs from leaf-level cost 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 cost centers, allowing flexible organizational grouping by functional area (e.g., Administration, Production, Sales, R&D).
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createCostCenterHierarchyNode](../commands/CreateCostCenterHierarchyNode.md) - Create a new hierarchy node as a child of an existing node or as the root node
+- [deleteCostCenterHierarchyNode](../commands/DeleteCostCenterHierarchyNode.md) - Delete a hierarchy node that has no child nodes or assigned cost centers
+- [moveCostCenterHierarchyNode](../commands/MoveCostCenterHierarchyNode.md) - Move a hierarchy node to a different parent within the same hierarchy
+
+### Query Definitions
+
+- [GetCostCenterHierarchy](../queries/GetCostCenterHierarchy.md) - Retrieve hierarchy nodes as part of the full hierarchy tree
+
+### Models
+
+- CostCenterHierarchyNode
+
+### Invariants
+
+- Hierarchy node requires a name
+- Hierarchy node must belong to a valid CostCenterHierarchy 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)
+- Deleting a hierarchy node that has child nodes is rejected; children must be reassigned or removed first
+- Deleting a hierarchy node that has assigned cost centers is rejected; cost centers must be reassigned first
+- Hierarchy nodes support parent-child relationships with a sort order and level attribute
+
+### Relationships
+
+- **Belongs to CostCenterHierarchy**: Each node belongs to a CostCenterHierarchy via hierarchyId
+- **Self-referencing Parent**: Each node optionally references a parent CostCenterHierarchyNode via parentNodeId
+- **Has Many CostCenter**: A hierarchy node can have multiple cost centers assigned to it