# README

## Overview

The accounting module provides management (internal) accounting capabilities for budgeting, cost allocation, profit center reporting, and variance analysis. It enables organizations to track, allocate, and analyze costs for internal decision-making, complementing the financial accounting capabilities provided by `finance-ledger` and `coa-management`.

This module owns cost centers, profit centers, cost elements, budgets, internal orders, and allocation cycles — entities that exist solely for management accounting purposes and are distinct from the general ledger structure.

## Key Features

- **Cost Center Management** — Create and maintain cost centers with hierarchical grouping for overhead cost accumulation and reporting
- **Cost Element Management** — Define primary cost elements (mapped to GL accounts) and secondary cost elements (internal allocation only)
- **Profit Center Management** — Create and maintain profit centers with hierarchical grouping for internal P&L reporting
- **Budget Management** — Create budgets with line items per cost element, manage approval workflows, track budget versions, and enforce budgetary control with commitment-aware availability checks
- **Cost Allocation** — Execute allocation cycles (assessment/distribution) to distribute overhead costs from sender to receiver cost objects
- **Internal Order Management** — Track costs for specific short-to-medium-term activities (projects, campaigns, events) with lifecycle management
- **Variance Analysis** — Compare planned vs. actual costs by cost object and period, categorize variances, and generate management reports

## Module Scope

### In Scope

- Cost center CRUD and hierarchy management
- Profit center CRUD and hierarchy management
- Primary and secondary cost element definition
- Budget creation, approval workflow, and line item entry per cost element
- Budgetary control with commitment-aware availability checks (Budget - Actual - Commitments - Encumbrances)
- Commitment tracking via purchase module event consumption (PO confirmed, received, invoiced, cancelled)
- Budget vs. actual comparison
- Cost allocation cycles (assessment and distribution methods)
- Allocation rule definition and execution
- Internal order lifecycle (created → released → technically completed → closed)
- Variance calculation and categorization (plan vs. actual) with cost-element-level detail lines
- Multi-version planning (budget, forecast)
- Audit trail for budget changes, allocation runs, and variance postings

### Out of Scope

- Financial (external) accounting — owned by `finance-ledger`
- Chart of accounts and GL account management — owned by `coa-management`
- Fiscal year and accounting period management — owned by `finance-ledger`
- Activity-based costing (activity types, rate calculation) — future extension
- Statistical key figures as allocation drivers — future extension
- Multi-dimensional profitability analysis (CO-PA style) — future extension
- What-if scenario modeling and simulation — future extension
- Internal order settlement to receivers — future extension
- Rolling forecasts beyond fiscal year boundaries — future extension
- Manufacturing variance calculation — owned by `manufacturing`; this module consumes results
- Transfer pricing between legal entities — future extension

### Scope Decision Rationale

The initial scope focuses on the six core entities identified in the roadmap (Budget, BudgetLine, ProfitCenter, CostAllocation, InternalOrder, Variance) plus foundational entities (CostCenter, CostElement) required by all management accounting features. Comprehensive features like activity-based costing and multi-dimensional profitability analysis are deferred as they add significant complexity without being prerequisites for the core budgeting-allocation-variance workflow. The module explicitly does not recreate entities already owned by other modules (fiscal calendar from finance-ledger, GL accounts from coa-management, manufacturing variances from manufacturing).

## Module Dependencies

- `primitives` — Currency definitions for multi-currency budget amounts and variance values
- `organization` — Company scoping for all management accounting entities; Department/Site as optional mapping targets for cost centers and profit centers
- `coa-management` — GL account references for primary cost elements, budget line items, and allocation target accounts
- `finance-ledger` — Fiscal year/period alignment for budget periods; journal entry data as source of actuals; subledger integration pattern for posting allocation journal entries
- `purchase` — Commitment event consumption for budgetary control: PO confirmation creates commitments, goods receipt and invoice match consume commitments, PO cancellation releases commitments
- `user-management` — Permission definitions for budget creation, allocation execution, and report access
- `audit` — Audit trail for budget lifecycle transitions, allocation runs, and variance postings
