README

Enterprise-grade cost accounting and management package for the Nexus ERP system.

Overview

The Nexus\CostAccounting package provides comprehensive cost management capabilities including cost center management, cost pool aggregation, product costing, and cost allocation. It serves as the cost control layer that enables organizations to track, allocate, and analyze costs across their operational units using both traditional costing and Activity-Based Costing (ABC) methodologies.

Key Features

🎯 Core Capabilities

• Cost Center Management: Hierarchical organizational units for cost collection and responsibility tracking
• Cost Pool Aggregation: Indirect cost pooling for overhead allocation
• Cost Element Classification: Material, Labor, and Overhead categorization
• Product Cost Calculation: Multi-level cost rollup with standard and actual cost tracking
• Cost Allocation: Multiple allocation methods (Direct, Step-Down, Reciprocal) with ABC support
• Variance Analysis: Tracking and reporting of actual versus standard cost variances

🔄 Cost Allocation Methods

• Direct Allocation: Allocates costs directly from source to receiving cost centers based on allocation ratios
• Step-Down Allocation: Allocates costs sequentially from service cost centers to production cost centers
• Reciprocal Allocation: Allocates costs using simultaneous equations to handle reciprocal relationships

📊 Product Costing

• Standard Costing: Pre-determined costs for planning and control
• Actual Costing: Real costs incurred for accurate product valuation
• Multi-Level Rollup: Cost accumulation through bill of materials hierarchies
• Unit Cost Calculation: Per-unit cost determination for pricing and profitability

🔐 Financial Controls

• Tenant Isolation: Multi-tenant data security with per-tenant cost center hierarchies
• Period-Based Costing: Fiscal period validation and cost tracking
• Budget Integration: Cost center linkage to budget management
• GL Mapping: Integration with chart of accounts for cost posting

Architecture

Framework Agnosticism

This package contains pure PHP logic and is completely framework-agnostic:

• ✅ No Laravel dependencies in /src
• ✅ All dependencies via contracts (interfaces)
• ✅ Readonly constructor property promotion
• ✅ Native PHP 8.3 enums with business logic
• ✅ Immutable value objects
• ✅ PSR-3 logging, PSR-14 event dispatching

Directory Structure

src/
├── Contracts/
│   ├── CostAccountingManagerInterface.php     # Primary facade
│   ├── CostCenterManagerInterface.php        # Cost center management
│   ├── CostCenterQueryInterface.php           # CQRS: Read operations
│   ├── CostCenterPersistInterface.php         # CQRS: Write operations
│   ├── CostPoolQueryInterface.php            # Pool queries
│   ├── CostPoolPersistInterface.php           # Pool persistence
│   ├── ProductCostCalculatorInterface.php     # Product costing
│   ├── CostAllocationEngineInterface.php      # Allocation execution
│   └── Integration/                           # External package integrations
├── Entities/
│   ├── CostCenter.php                         # Cost center entity
│   ├── CostPool.php                           # Cost pool entity
│   ├── CostElement.php                        # Cost element entity
│   ├── ProductCost.php                        # Product cost entity
│   └── CostAllocationRule.php                 # Allocation rule entity
├── Enums/
│   ├── AllocationMethod.php                   # Direct, Step-Down, Reciprocal
│   ├── CostElementType.php                   # Material, Labor, Overhead
│   └── CostCenterStatus.php                  # Active, Inactive, Pending
├── ValueObjects/
│   ├── CostAmount.php                         # Immutable monetary amount
│   ├── CostAllocationRatio.php               # Validated allocation percentages
│   ├── CostCenterHierarchy.php               # Tree structure
│   ├── ProductCostSnapshot.php                # Historical cost capture
│   ├── CostVarianceBreakdown.php             # Variance analysis
│   └── ActivityDriver.php                     # ABC driver
├── Services/
│   ├── CostAccountingManager.php              # Main orchestrator
│   ├── CostCenterManager.php                  # Center management
│   ├── ProductCostCalculator.php              # Cost calculations
│   └── CostAllocationEngine.php              # Allocation execution
├── Exceptions/
│   ├── CostAccountingException.php            # Base exception
│   ├── CostCenterNotFoundException.php        # Not found
│   ├── InvalidAllocationRuleException.php     # Validation
│   ├── AllocationCycleDetectedException.php   # Circular dependency
│   ├── InsufficientCostPoolException.php      # Pool balance
│   └── ProductCostNotFoundException.php       # Not found
└── Events/
    └── CostCenterCreatedEvent.php             # Domain event

Integration Points

Installation

1. Add to Root Composer

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/CostAccounting"
        }
    ]
}

2. Install Package

composer require azaharizaman/nexus-cost-accounting:"*@dev"

3. Register Service Provider (Laravel)

In apps/Atomy/config/app.php:

'providers' => [
    // ...
    App\Providers\CostAccountingServiceProvider::class,
],

4. Run Migrations

php artisan migrate

Quick Start

Create a Cost Center

use Nexus\CostAccounting\Contracts\CostAccountingManagerInterface;
use Nexus\CostAccounting\Enums\CostCenterStatus;

$manager = app(CostAccountingManagerInterface::class);

$costCenter = $manager->createCostCenter([
    'code' => 'CC-MFG-001',
    'name' => 'Manufacturing Unit 1',
    'description' => 'Main manufacturing facility',
    'tenant_id' => '01TENANT...',
    'status' => CostCenterStatus::Active,
    'cost_center_type' => 'production',
    'responsible_person_id' => '01USER...',
]);

Create a Cost Pool

use Nexus\CostAccounting\Enums\AllocationMethod;

$pool = $manager->createCostPool([
    'code' => 'CP-OVERHEAD-001',
    'name' => 'Factory Overhead',
    'description' => 'Indirect manufacturing costs',
    'cost_center_id' => $costCenter->getId(),
    'period_id' => '01PERIOD-2026-Q1',
    'tenant_id' => '01TENANT...',
    'allocation_method' => AllocationMethod::StepDown,
    'total_amount' => 50000.00,
]);

Allocate Pool Costs

use Nexus\CostAccounting\Exceptions\AllocationCycleDetectedException;
use Nexus\CostAccounting\Exceptions\InvalidAllocationRuleException;

try {
    $allocationResult = $manager->allocatePoolCosts(
        poolId: $pool->getId(),
        periodId: '01PERIOD-2026-Q1'
    );
    
    foreach ($allocationResult['allocations'] as $costCenterId => $amount) {
        echo "Allocated {$amount} to cost center {$costCenterId}";
    }
} catch (AllocationCycleDetectedException $e) {
    echo "Circular allocation detected: " . $e->getMessage();
} catch (InvalidAllocationRuleException $e) {
    echo "Invalid allocation rule: " . $e->getMessage();
}

Calculate Product Cost

use Nexus\CostAccounting\Enums\CostType;

$productCost = $manager->calculateProductCost(
    productId: '01PRODUCT-A001',
    periodId: '01PERIOD-2026-Q1',
    costType: CostType::Standard
);

echo "Material: " . $productCost->getMaterialCost();
echo "Labor: " . $productCost->getLaborCost();
echo "Overhead: " . $productCost->getOverheadCost();
echo "Total: " . $productCost->getTotalCost();

Perform Cost Rollup

$snapshot = $manager->performCostRollup(
    productId: '01PRODUCT-A001',
    periodId: '01PERIOD-2026-Q1'
);

echo "Level {$snapshot->getLevel()}: Total Cost = {$snapshot->getTotalCost()}";
echo "Unit Cost: {$snapshot->getUnitCost()}";

Calculate Variances

$variance = $manager->calculateVariances(
    productId: '01PRODUCT-A001',
    periodId: '01PERIOD-2026-Q1'
);

echo "Price Variance: {$variance->getPriceVariance()}";
echo "Rate Variance: {$variance->getRateVariance()}";
echo "Efficiency Variance: {$variance->getEfficiencyVariance()}";
echo "Total Variance: {$variance->getTotalVariance()}";

if ($variance->isFavorable()) {
    echo "Variance is favorable (costs under standard)";
} else {
    echo "Variance is unfavorable (costs over standard)";
}

Get Cost Center Hierarchy

$hierarchy = $manager->getCostCenterHierarchy();

$roots = $hierarchy->getRootCostCenters();
foreach ($roots as $root) {
    echo "Root: {$root->getName()}";
    
    $children = $hierarchy->getChildren($root->getId());
    foreach ($children as $child) {
        echo "  Child: {$child->getName()}";
    }
}

Key Interfaces

CostAccountingManagerInterface

Primary facade providing access to all cost accounting operations:

createCostCenter(array $data): CostCenter
updateCostCenter(string $costCenterId, array $data): CostCenter
getCostCenterHierarchy(?string $rootCostCenterId = null): CostCenterHierarchy
createCostPool(array $data): CostPool
allocatePoolCosts(string $poolId, string $periodId): array
calculateProductCost(string $productId, string $periodId, CostType $costType): ProductCost
performCostRollup(string $productId, string $periodId): ProductCostSnapshot
calculateVariances(string $productId, string $periodId): CostVarianceBreakdown

CostAllocationEngineInterface

Executes cost allocation from pools to receiving cost centers:

allocate(CostPool $pool, string $periodId): array
validateAllocationRules(CostPool $pool): array
detectCircularDependencies(CostAllocationRule $rule): bool
calculateActivityRates(string $costCenterId, string $periodId): array
allocateStepDown(CostPool $pool, string $periodId, array $order): array
allocateReciprocal(array $pools, string $periodId): array

ProductCostCalculatorInterface

Handles product cost calculations:

calculate(string $productId, string $periodId, CostType $costType): ProductCost
Note: Uses CostType enum (Standard, Actual) for type-safe cost type handling.
calculateStandardCost(string $productId, string $periodId): ProductCost
calculateActualCost(string $productId, string $periodId): ProductCost
rollup(string $productId, string $periodId): ProductCostSnapshot
calculateUnitCost(string $productId, string $periodId, float $quantity): float

CostCenterManagerInterface

Cost center CRUD operations:

create(array $data): CostCenter
update(string $costCenterId, array $data): CostCenter
delete(string $costCenterId): void
updateStatus(string $costCenterId, CostCenterStatus $status): void
assignParent(string $costCenterId, ?string $parentCostCenterId): void
linkBudget(string $costCenterId, string $budgetId): void

Domain Model

Entities

Value Objects

Enums

Exceptions

Configuration

Settings (via Nexus\Setting)

'cost_accounting.default_allocation_method' => 'step_down',
'cost_accounting.variance_investigation_threshold' => 5.0,      // Percentage
'cost_accounting.enable_abc' => true,
'cost_accounting.cost_calculation_timeout' => 30,             // Seconds
'cost_accounting.max_hierarchy_depth' => 10,

Event Catalog

Published Events

• CostCenterCreatedEvent - New cost center created

Subscribed Events

• Nexus\Period\Events\PeriodClosedEvent - Process period-end allocations
• Nexus\Inventory\Events\InventoryValuationUpdatedEvent - Update material costs
• Nexus\Manufacturing\Events\ProductionCompletedEvent - Record actual costs

Requirements

This package implements 78 requirements covering:

• 6 Architectural Requirements (framework-agnostic, interfaces, immutability)
• 10 Business Requirements (cost centers, pools, allocation, product costing)
• 15 Functional Requirements (CRUD, calculations, reporting)
• 8 Integration Requirements (external package interfaces)
• 8 Interface Requirements (contracts)
• 6 Value Object Requirements
• 6 Exception Requirements
• 3 Security Requirements (tenant isolation, authorization, audit)
• 3 Performance Requirements
• 3 Reliability Requirements (deterministic, idempotent, rollback)
• 3 Documentation Requirements
• 3 Testing Requirements

For detailed requirements, see REQUIREMENTS.md.

Architecture (see ARCHITECTURE.md)

For detailed architecture documentation, see ARCHITECTURE.md which covers:

• Package overview and scope
• Architecture principles (framework-agnostic, DI, CQRS, immutability)
• Directory structure
• Entity relationships
• Service orchestration
• Integration patterns

Development

Testing

# Package tests (framework-agnostic)
vendor/bin/phpunit packages/CostAccounting/tests

# Atomy integration tests
php artisan test --filter CostAccounting

Code Style

This package follows strict coding standards:

• PHP 8.3+ with strict typing
• declare(strict_types=1) in all files
• Readonly properties for immutability
• Constructor property promotion
• PSR-12 coding standards
• Comprehensive docblocks

Documentation

Package Documentation

• Architecture - Detailed architecture documentation
• Requirements - Complete requirements traceability (78 requirements)
• Getting Started Guide - Quick start guide
• API Reference - Complete API documentation
• Implementation Summary - Implementation details and progress

Additional Resources

• docs/examples/ - Usage examples
• See root ARCHITECTURE.md for overall system architecture
• See root ACCOUNTING_OPERATIONS_FINAL_STRUCTURE.md for orchestration context

License

MIT License - See LICENSE file for details.

Support

For questions or issues, please refer to the main Nexus documentation or contact the development team.