README

Atomic, stateless package for managing bank accounts, bank statement imports, cash reconciliation, and liquidity forecasting—strictly decoupled from GL ownership.

Overview

The Nexus\CashManagement package provides comprehensive cash and bank account management capabilities within the Nexus ERP ecosystem. It focuses on:

Bank Account Management: Master data for company bank accounts with multi-currency support
Statement Import: Configurable CSV import with duplicate detection and validation
Automatic Reconciliation: AI-assisted matching of bank transactions to ERP records (Payments, Receipts, GL entries)
Manual Reconciliation: Review and approval workflow for unmatched transactions
Cash Flow Forecasting: Deterministic and AI-powered multi-scenario forecasting
Cash Position Tracking: Real-time cash position across all bank accounts

Core Philosophy

Strict Decoupling

This package adheres to the "Logic in Packages, Implementation in Applications" principle:

Framework-Agnostic: Pure PHP with zero Laravel dependencies
Contract-Driven: All dependencies expressed via interfaces
Stateless Operations: No GL posting—only reconciliation and classification
Integration via Events: Consumes Nexus\Import events for statement data

Separation of Concerns

Nexus\Import          → Parses CSV files → Emits StatementLineDTO[]
Nexus\CashManagement  → Consumes DTOs   → Creates BankStatement entities → Matches transactions
Nexus\Finance         → Receives post commands → Creates Journal Entries

Architecture

Key Design Decisions

AuditLogger for Timeline (V1): All reconciliation events logged for user-facing timeline
EventStream Optional (V2): Available for large enterprises requiring SOX compliance and temporal queries
Manual GL Posting: Reconciliation engine creates PendingAdjustment entities; user manually posts to GL
Auto-Reversal: Rejected pending adjustments automatically reverse payment applications via workflow
AI Governance: Model versioning tracked in PendingAdjustment for explainability

Integration Points

Nexus\Finance: GL account validation, journal entry posting
Nexus\Receivable: Payment application matching and reversal
Nexus\Payable: Payment matching for outflows
Nexus\Period: Period validation for transaction dates
Nexus\Currency: Multi-currency exchange rates (V2)
Nexus\Sequencing: Auto-numbering for statements and reconciliations
Nexus\Import: CSV file parsing and standardization
Nexus\Setting: Feature flags and configuration
Nexus\Workflow: High-value variance escalation and reversal approval
Nexus\Intelligence (optional): AI-powered classification and forecasting
Nexus\QueryEngine (optional): Cash Conversion Cycle and bank fee analysis

Features

Bank Account Management

$bankAccount = $cashManager->createBankAccount(
    tenantId: $tenantId,
    accountCode: '1000-01',
    glAccountId: $glAccountId,
    accountNumber: '1234567890',
    bankName: 'Maybank',
    bankCode: 'MBB',
    accountType: BankAccountType::CHECKING,
    currency: 'MYR',
    csvImportConfig: [
        'date_column' => 'Transaction Date',
        'description_column' => 'Description',
        'debit_column' => 'Debit',
        'credit_column' => 'Credit',
        'balance_column' => 'Balance'
    ]
);

Statement Import

// Import via Nexus\Import package (emits FileImportedEvent)
// BankStatementImportedListener consumes event and creates entities

$result = $cashManager->reconcileStatement($statementId);

echo "Matched: {$result->getMatchedCount()}\n";
echo "Unmatched: {$result->getUnmatchedCount()}\n";

Cash Flow Forecasting

$parameters = ScenarioParametersVO::fromScenarioType(
    ForecastScenarioType::BASELINE,
    horizonDays: 90
);

$forecast = $cashFlowForecaster->forecast($tenantId, $parameters);

if ($forecast->hasNegativeBalance()) {
    // Alert: Liquidity risk detected
}

Pending Adjustment Posting

// User reviews unmatched transaction
$cashManager->postPendingAdjustment(
    pendingAdjustmentId: $adjustmentId,
    glAccount: '6200', // Bank Fees Expense
    postedBy: $userId
);

// If user rejects (wrong match):
$cashManager->rejectPendingAdjustment(
    pendingAdjustmentId: $adjustmentId,
    reason: 'Incorrect match - customer deposit',
    rejectedBy: $userId
);
// Triggers automatic payment application reversal + GL workflow

Value Objects

BankAccountNumber: Validated bank account with IBAN/SWIFT support
StatementPeriod: Date range with overlap detection
ReconciliationTolerance: Amount/date variance thresholds
CashPosition: Point-in-time balance snapshot
CSVColumnMapping: Import configuration
ScenarioParametersVO: Forecast scenario parameters
ForecastResultVO: Persistable forecast output
StatementHash: Cryptographic deduplication
AIModelVersion: Semantic versioning for AI models

Enums

BankAccountType: CHECKING, SAVINGS, CREDIT_CARD, MONEY_MARKET, LINE_OF_CREDIT
BankAccountStatus: ACTIVE, INACTIVE, CLOSED, SUSPENDED
BankTransactionType: DEPOSIT, WITHDRAWAL, TRANSFER, FEE, INTEREST, etc.
ReconciliationStatus: PENDING, MATCHED, VARIANCE_REVIEW, RECONCILED, UNMATCHED, REJECTED
MatchingConfidence: HIGH, MEDIUM, LOW, MANUAL
ForecastScenarioType: OPTIMISTIC, BASELINE, PESSIMISTIC, CUSTOM

Exceptions

BankAccountNotFoundException
DuplicateStatementException
PartialOverlapException
ReconciliationException
ReversalRequiredException
InvalidStatementFormatException
UnmatchedTransactionsException

Multi-Currency Support (V2)

The package schema is V2-ready with nullable columns:

transaction_currency
exchange_rate
functional_amount

Multi-currency activation requires:

$featureManager->isEnabled('multi_currency_banking')

Dependencies

azaharizaman/nexus-finance - GL integration
azaharizaman/nexus-receivable - Payment application
azaharizaman/nexus-payable - Payment matching
azaharizaman/nexus-period - Period validation
azaharizaman/nexus-currency - Exchange rates
azaharizaman/nexus-sequencing - Auto-numbering
azaharizaman/nexus-import - Statement parsing
azaharizaman/nexus-setting - Configuration
azaharizaman/nexus-workflow - Approval processes

Optional Dependencies

azaharizaman/nexus-intelligence - AI classification/forecasting
azaharizaman/nexus-query-engine - KPI calculation

Installation

composer require azaharizaman/nexus-cash-management:"*@dev"

📖 Documentation

Package Documentation

Getting Started Guide - Quick start guide with prerequisites, concepts, and first integration
API Reference - Complete documentation of all interfaces, value objects, enums, and exceptions
Integration Guide - Laravel and Symfony integration examples with complete setup
Basic Usage Example - Import statement, auto-reconcile, approve/reject adjustments
Advanced Usage Example - Cash flow forecasting, AI feedback, high-value workflows, multi-currency

Additional Resources

IMPLEMENTATION_SUMMARY.md - Implementation progress, metrics, and architecture details
REQUIREMENTS.md - Detailed requirements (58 requirements, 96.6% complete)
TEST_SUITE_SUMMARY.md - Test coverage strategy and recommendations
VALUATION_MATRIX.md - Package valuation metrics ($140,576 estimated value)
See root ARCHITECTURE.md for overall system architecture

License

MIT License. See LICENSE file for details.

azaharizaman / nexus-cash-management

Maintainers

Package info

Statistics

Security