README

Treasury management package for cash flow forecasting, investment management, and approval workflows.

Purpose

The Treasury package provides a comprehensive domain model and service layer for managing treasury operations within the Nexus platform. It handles policy management, authorization limits, and approval workflows for financial transactions.

Key Features

Treasury Policy Management: Create and manage treasury policies with configurable thresholds
Authorization Limits: Define spending limits per user or role with currency support
Approval Workflows: Submit, approve, or reject transactions requiring authorization
Multi-Currency Support: All monetary values support multiple currencies
Status Tracking: Comprehensive status management for policies and approvals

Installation

composer require azaharizaman/nexus-treasury

Requirements

PHP ^8.3
azaharizaman/nexus-common ^1.0

Usage

Creating a Treasury Policy

use Nexus\Treasury\Services\TreasuryManager;
use Nexus\Treasury\ValueObjects\TreasuryPolicyData;

// Create policy data
$policyData = TreasuryPolicyData::fromArray([
    'name' => 'Corporate Treasury Policy',
    'description' => 'Main treasury policy for corporate operations',
    'minimum_cash_balance' => 100000.00,
    'minimum_cash_balance_currency' => 'USD',
    'maximum_single_transaction' => 500000.00,
    'maximum_single_transaction_currency' => 'USD',
    'approval_required' => true,
    'approval_threshold' => 50000.00,
    'approval_threshold_currency' => 'USD',
]);

// Create policy via TreasuryManager
$policy = $treasuryManager->createPolicy($tenantId, $policyData);
echo $policy->getId(); // TRS-POL-XXXXX

Managing Authorization Limits

use Nexus\Treasury\ValueObjects\AuthorizationLimit;

// Create an authorization limit for a user
$limit = new AuthorizationLimit(
    userId: 'user-123',
    roleId: null,
    amount: 25000.00,
    currency: 'USD',
    transactionType: 'payment'
);

$authLimit = $treasuryManager->createAuthorizationLimit($tenantId, $limit);

// Check if transaction requires approval
$requiresApproval = $treasuryManager->requiresApproval(
    $tenantId,
    30000.00,
    'USD'
);

Approval Workflow

// Submit a transaction for approval
$approval = $treasuryManager->submitForApproval(
    $tenantId,
    'payment',
    75000.00,
    'USD',
    'Vendor payment for services',
    'user-123'
);

// Get pending approvals for a user
$pendingApprovals = $treasuryManager->getPendingApprovals('approver-456');

// Approve the transaction
$approved = $treasuryManager->approveTransaction(
    $approval->getId(),
    'approver-456',
    'Approved - within budget'
);

// Or reject the transaction
$rejected = $treasuryManager->rejectTransaction(
    $approval->getId(),
    'approver-456',
    'Insufficient budget allocation'
);

Interfaces

Core Interfaces

Interface	Description
`TreasuryManagerInterface`	Main orchestrator for treasury operations
`TreasuryPolicyInterface`	Treasury policy entity contract
`TreasuryApprovalInterface`	Treasury approval entity contract
`AuthorizationLimitInterface`	Authorization limit entity contract

Repository Interfaces

Interface	Description
`TreasuryPolicyRepositoryInterface`	Combined repository for policy persistence
`TreasuryPolicyQueryRepositoryInterface`	Read operations for policies
`TreasuryPolicyPersistRepositoryInterface`	Write operations for policies
`TreasuryApprovalRepositoryInterface`	Combined repository for approval persistence
`TreasuryApprovalQueryRepositoryInterface`	Read operations for approvals
`TreasuryApprovalPersistRepositoryInterface`	Write operations for approvals
`AuthorizationLimitRepositoryInterface`	Combined repository for limit persistence
`AuthorizationLimitQueryRepositoryInterface`	Read operations for limits
`AuthorizationLimitPersistRepositoryInterface`	Write operations for limits

Models

Model	Description
`TreasuryPolicy`	Immutable treasury policy entity
`TreasuryApproval`	Immutable approval entity
`AuthorizationLimit`	Immutable authorization limit entity

Value Objects

Value Object	Description
`TreasuryPolicyData`	Data transfer object for policy creation/update
`AuthorizationLimit`	Data transfer object for limit creation

Enums

Enum	Cases	Description
`ApprovalStatus`	PENDING, APPROVED, REJECTED, CANCELLED, EXPIRED, REQUIRES_REVIEW	Status of approval requests
`TreasuryStatus`	ACTIVE, INACTIVE, PENDING, SUSPENDED, CLOSED	Status of treasury policies
`InvestmentType`	MONEY_MARKET, TERM_DEPOSIT, TREASURY_BILL, COMMERCIAL_PAPER, FIXED_DEPOSIT, OVERNIGHT	Types of short-term investments
`InvestmentStatus`	PENDING, ACTIVE, MATURED, CANCELLED	Status of investments
`ForecastScenario`	OPTIMISTIC, BASE, PESSIMISTIC	Cash flow forecast scenarios

Exceptions

Exception	Description
`TreasuryException`	Base exception for treasury operations
`TreasuryPolicyNotFoundException`	Thrown when policy is not found
`LiquidityPoolNotFoundException`	Thrown when liquidity pool is not found

Architecture

This package follows the Atomic Architecture pattern:

Contracts: Interface definitions for domain contracts
Models: Immutable entity implementations
ValueObjects: Data transfer objects for operations
Services: Business logic and orchestration
Repositories: In-memory implementations for testing
Enums: Type-safe enumerations
Exceptions: Domain-specific exceptions

Testing

# Run tests
./vendor/bin/phpunit

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage

License

MIT License

azaharizaman / nexus-treasury

Maintainers

Package info

Statistics

Security