@tailor-platform/erp-kit 0.7.0 → 0.8.0

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

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