README

Enterprise-grade fixed asset depreciation calculation engine with Progressive Delivery for Small Business to Large Enterprise.

Overview

The Nexus\FixedAssetDepreciation package provides a comprehensive depreciation calculation engine for fixed assets within the Nexus ERP system. It serves as the specialized depreciation layer that enables organizations to calculate, track, and manage asset depreciation using multiple methodologies compliant with both GAAP and IFRS accounting standards.

This package extends beyond basic depreciation offered in the Nexus\Assets package by providing:

• Advanced calculation methods beyond basic straight-line
• Comprehensive schedule management with forecasting
• Tax vs Book parallel depreciation
• IFRS-compliant revaluation model
• Automated GL journal entry integration

Key Features

🎯 Core Capabilities

• Multiple Depreciation Methods: Straight-Line, Double Declining, Sum-of-Years-Digits, Units of Production, Annuity, MACRS
• Depreciation Scheduling: Automated schedule generation, adjustment, and forecasting
• Asset Revaluation: IFRS IAS 16 compliant revaluation with equity adjustments
• Tax-Book Reconciliation: Parallel calculation for tax reporting and book purposes
• GL Integration: Automated journal entry posting for depreciation expense
• Impairment Support: Partial asset impairment calculations

🔄 Depreciation Methods

🔐 Financial Controls

• Tenant Isolation: Multi-tenant data security with per-tenant depreciation configurations
• Period-Based Depreciation: Fiscal period validation and depreciation tracking
• GL Account Mapping: Integration with chart of accounts for expense and accumulated depreciation
• Audit Trail: Comprehensive logging via Nexus\Audit
• Approval Workflows: Optional approval for revaluations (Tier 3)

Progressive Feature Tiers

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/
│   ├── DepreciationManagerInterface.php          # Primary facade
│   ├── DepreciationCalculatorInterface.php       # Calculation engine
│   ├── DepreciationScheduleManagerInterface.php  # Schedule management
│   ├── AssetRevaluationInterface.php             # Revaluation operations
│   ├── DepreciationMethodInterface.php            # Method abstraction
│   ├── DepreciationQueryInterface.php             # CQRS: Read operations
│   ├── DepreciationPersistInterface.php           # CQRS: Write operations
│   └── Integration/                               # External package integrations
├── Entities/
│   ├── AssetDepreciation.php                     # Depreciation entity
│   ├── DepreciationSchedule.php                  # Schedule entity
│   ├── DepreciationMethod.php                    # Method entity
│   ├── AssetRevaluation.php                      # Revaluation entity
│   └── DepreciationAdjustment.php                # Adjustment entity
├── Enums/
│   ├── DepreciationMethodType.php                 # SL, DDB, SYD, UOP, Annuity
│   ├── DepreciationStatus.php                    # Calculated, Posted, Reversed
│   ├── RevaluationType.php                       # Increment, Decrement
│   ├── DepreciationType.php                       # Book, Tax
│   └── ProrateConvention.php                      # Full month, Daily, None
├── ValueObjects/
│   ├── DepreciationAmount.php                    # Immutable depreciation amount
│   ├── DepreciationSchedulePeriod.php            # Single period schedule
│   ├── DepreciationForecast.php                  # Future depreciation
│   ├── BookValue.php                             # Current book value
│   ├── RevaluationAmount.php                     # Revaluation delta
│   └── DepreciationLife.php                     # Useful life and salvage
├── Services/
│   ├── DepreciationManager.php                    # Main orchestrator
│   ├── DepreciationCalculator.php                # Calculation engine
│   ├── DepreciationScheduleGenerator.php         # Schedule generation
│   ├── AssetRevaluationService.php               # Revaluation logic
│   ├── DepreciationMethodFactory.php             # Method instantiation
│   └── TaxBookDepreciationEngine.php             # Tax vs Book parallel
├── Exceptions/
│   ├── DepreciationException.php                 # Base exception
│   ├── DepreciationCalculationException.php      # Calculation error
│   ├── InvalidDepreciationMethodException.php    # Invalid method
│   ├── AssetNotDepreciableException.php          # Non-depreciable asset
│   ├── DepreciationPeriodClosedException.php    # Period closed
│   ├── RevaluationException.php                 # Revaluation error
│   └── ScheduleNotFoundException.php            # Schedule not found
└── Events/
    ├── DepreciationCalculatedEvent.php           # Calculation complete
    ├── DepreciationPostedEvent.php               # JE posted
    ├── DepreciationReversedEvent.php            # Reversal complete
    ├── AssetRevaluedEvent.php                    # Revaluation complete
    └── DepreciationScheduleAdjustedEvent.php    # Schedule modified

Integration Points

Installation

1. Add to Root Composer

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

2. Install Package

composer require azaharizaman/nexus-fixed-asset-depreciation:"*@dev"

3. Register Service Provider (Laravel)

In apps/Atomy/config/app.php:

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

4. Configure Tier

Set the tier for your tenant in application settings:

use Nexus\Setting\SettingManager;

$settings->setString('fixed_asset_depreciation.tier', 'basic'); // or 'advanced', 'enterprise'

Quick Start

Tier 1: Basic Depreciation

use Nexus\FixedAssetDepreciation\Contracts\DepreciationManagerInterface;
use Nexus\FixedAssetDepreciation\Enums\DepreciationMethodType;
use Nexus\FixedAssetDepreciation\Enums\DepreciationType;

$manager = app(DepreciationManagerInterface::class);

// Calculate depreciation for a single asset in a period
$depreciation = $manager->calculateDepreciation(
    assetId: '01ASSET-A001',
    periodId: '01PERIOD-2026-01'
);

echo "Depreciation Amount: " . $depreciation->getDepreciationAmount()->getAmount();
echo "Book Value After: " . $depreciation->getBookValueAfter()->getNetBookValue();

Generate Depreciation Schedule

// Generate full depreciation schedule for an asset
$schedule = $manager->generateSchedule(assetId: '01ASSET-A001');

foreach ($schedule->getPeriods() as $period) {
    echo "Period: " . $period->getPeriodId();
    echo "Depreciation: " . $period->getDepreciationAmount();
    echo "Book Value: " . $period->getNetBookValue();
}

Run Periodic Depreciation (Monthly)

// Process all assets for period-end depreciation
$result = $manager->runPeriodicDepreciation(
    periodId: '01PERIOD-2026-01'
);

echo "Processed: " . $result->getProcessedCount() . " assets";
echo "Total Depreciation: " . $result->getTotalDepreciation();

Reverse Depreciation

// Reverse a depreciation calculation (e.g., due to error)
$manager->reverseDepreciation(
    depreciationId: '01DEP-2026-01-001',
    reason: 'Incorrect useful life used'
);

Asset Revaluation (Tier 2+)

use Nexus\FixedAssetDepreciation\Enums\RevaluationType;

// Revalue an asset (IFRS IAS 16 compliant)
$revaluation = $manager->revalueAsset(
    assetId: '01ASSET-A001',
    newValue: 15000.00,
    newSalvageValue: 1500.00,
    revaluationType: RevaluationType::INCREMENT,
    reason: 'Market value increase',
    glAccountId: '01GL-REVALUATION'
);

echo "Revaluation Amount: " . $revaluation->getRevaluationAmount()->getAmount();
echo "New Book Value: " . $revaluation->getNewBookValue()->getNetBookValue();

Tax Depreciation (Tier 3)

// Calculate tax depreciation (MACRS) parallel to book depreciation
$taxDepreciation = $manager->calculateTaxDepreciation(
    assetId: '01ASSET-A001',
    taxMethod: 'MACRS',
    taxYear: 2026
);

echo "Tax Depreciation: " . $taxDepreciation->getAmount();
echo "Book Depreciation: " . $bookDepreciation->getAmount();
echo "Tax vs Book Difference: " . $taxDepreciation->subtract($bookDepreciation);

Depreciation Forecast

// Forecast future depreciation
$forecast = $manager->forecastDepreciation(
    assetId: '01ASSET-A001',
    periods: 12 // Next 12 months
);

foreach ($forecast->getPeriodForecasts() as $period) {
    echo $period->getPeriodId() . ": " . $period->getForecastedAmount();
}

Key Interfaces

DepreciationManagerInterface

Primary facade providing access to all depreciation operations:

calculateDepreciation(string $assetId, string $periodId): AssetDepreciation
generateSchedule(string $assetId): DepreciationSchedule
runPeriodicDepreciation(string $periodId): DepreciationRunResult
reverseDepreciation(string $depreciationId, string $reason): void
revalueAsset(string $assetId, float $newValue, RevaluationType $type): AssetRevaluation
calculateTaxDepreciation(string $assetId, string $taxMethod, int $taxYear): DepreciationAmount
forecastDepreciation(string $assetId, int $periods): DepreciationForecast

DepreciationCalculatorInterface

Core calculation engine:

calculate(string $assetId, ?DateTimeInterface $asOfDate, ?DepreciationType $type): DepreciationAmount
calculateForPeriod(string $assetId, string $periodId, ?DepreciationType $type): AssetDepreciation
forecast(string $assetId, int $numberOfPeriods): DepreciationForecast

DepreciationScheduleManagerInterface

Schedule management:

generate(string $assetId): DepreciationSchedule
adjust(string $scheduleId, array $adjustments): DepreciationSchedule
close(string $assetId): void
recalculate(string $assetId): DepreciationSchedule

AssetRevaluationInterface

Revaluation operations:

revalue(string $assetId, float $newCost, RevaluationType $type): AssetRevaluation
reverse(string $revaluationId): AssetRevaluation
getRevaluationHistory(string $assetId): array

Domain Model

Entities

Value Objects

Enums

Exceptions

Depreciation Formulas

Straight-Line (Tier 1)

Annual Depreciation = (Cost - Salvage) / Useful Life

Daily prorating for mid-month acquisitions:

Monthly = Annual / 12
Daily Proration = Monthly × (Days Owned / Days in Month)

Double Declining Balance (Tier 2)

Rate = 2 / Useful Life (years)
Year N Depreciation = Book Value at Start of Year × Rate
(Cannot depreciate below salvage value)

Sum-of-Years-Digits (Tier 2)

Sum = n(n+1)/2 where n = useful life
Year N Depreciation = (Cost - Salvage) × (Remaining Life / Sum)

Units of Production (Tier 3)

Depreciation = (Cost - Salvage) × (Units Produced / Total Expected Units)

Configuration

Settings (via Nexus\Setting)

'fixed_asset_depreciation.tier' => 'basic',  // basic|advanced|enterprise
'fixed_asset_depreciation.default_method' => 'STRAIGHT_LINE',
'fixed_asset_depreciation.prorate_convention' => 'daily',  // daily|full_month|none
'fixed_asset_depreciation.auto_gl_post' => false,  // Tier 3
'fixed_asset_depreciation.enable_tax_depreciation' => false,  // Tier 3
'fixed_asset_depreciation.max_forecast_periods' => 60,

GL Account Mapping

// Default GL accounts (can be overridden per asset category)
'fixed_asset_depreciation.gl_defaults' => [
    'depreciation_expense' => '6000-DEPR-EXP',
    'accumulated_depreciation' => '1600-ACCUM-DEPR',
    'gains_on_disposal' => '7000-GAIN-DISP',
    'losses_on_disposal' => '8000-LOSS-DISP',
    'revaluation_reserve' => '2500-REVAL-RES',
],

Event Catalog

Published Events

• DepreciationCalculatedEvent - Single depreciation calculation complete
• DepreciationPostedEvent - Journal entry posted to GL
• DepreciationReversedEvent - Depreciation reversed
• AssetRevaluedEvent - Asset revaluation complete
• DepreciationScheduleAdjustedEvent - Schedule modified
• DepreciationRunCompletedEvent - Batch depreciation run complete

Subscribed Events

• Nexus\Assets\Events\AssetAcquiredEvent - Generate initial depreciation schedule
• Nexus\Assets\Events\AssetDisposedEvent - Close depreciation schedule
• Nexus\Period\Events\PeriodClosedEvent - Process period-end depreciation

Requirements

This package implements comprehensive requirements covering:

• Architectural Requirements: Framework-agnostic, interfaces, immutability
• Business Requirements: Depreciation methods, schedules, revaluation
• Functional Requirements: CRUD, calculations, reporting
• Integration Requirements: External package interfaces
• Security Requirements: Tenant isolation, authorization
• Performance Requirements: Batch processing, forecasting

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
• Progressive delivery tiers

Development

Testing

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

# Atomy integration tests
php artisan test --filter FixedAssetDepreciation

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
• Getting Started Guide - Quick start guide
• API Reference - Complete API documentation

Additional Resources

• docs/examples/ - Usage examples
• See root ARCHITECTURE.md for overall system architecture
• See plans/FINANCE_ECOSYSTEM_EXECUTION_PLAN.md for finance ecosystem 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.