README

Version: 1.0.0
Status: 🔵 In Development
Category: Compliance & Governance

Overview

Nexus\AmlCompliance is a framework-agnostic, atomic PHP package for Anti-Money Laundering (AML) risk assessment and transaction monitoring. It provides sophisticated risk scoring algorithms (0-100 scale) for parties and transactions, with automated Suspicious Activity Report (SAR) generation.

Purpose

Assess AML risk and detect suspicious financial activity:

AML Risk Scoring (0-100 scale) for customers, vendors, transactions
Transaction Monitoring for unusual patterns
SAR Generation (Suspicious Activity Reports)
Jurisdiction Risk assessment
Business Type Risk classification

Key Features

✅ Risk Score Calculation - 0-100 AML risk score with factor breakdown
✅ Transaction Monitoring - Detect unusual patterns (velocity, amounts, geography)
✅ SAR Generation - Automated suspicious activity reporting
✅ Jurisdiction Risk - Country-specific risk levels
✅ Business Type Risk - Industry-based risk classification
✅ Risk Thresholds - Configurable HIGH/MEDIUM/LOW thresholds
✅ Framework-Agnostic - Pure PHP 8.3+, works with any framework

Installation

composer require azaharizaman/nexus-aml-compliance

Quick Start

AML Risk Assessment

use Nexus\AmlCompliance\Services\AmlRiskAssessor;
use Nexus\AmlCompliance\Contracts\AmlRiskAssessorInterface;

// Inject via constructor
public function __construct(
    private readonly AmlRiskAssessorInterface $amlAssessor
) {}

// Assess party risk
$riskScore = $this->amlAssessor->assessParty(
    partyId: 'party-12345'
);

// Get overall score (0-100)
$score = $riskScore->getScore(); // e.g., 75

// Get risk level (HIGH/MEDIUM/LOW)
$level = $riskScore->getRiskLevel(); // RiskLevel::HIGH

// Get risk factors breakdown
$factors = $riskScore->getFactors();
// [
//     'jurisdiction_risk' => 30,
//     'business_type_risk' => 20,
//     'sanctions_match' => 25,
//     'transaction_patterns' => 0
// ]

Transaction Monitoring

use Nexus\AmlCompliance\Services\TransactionMonitor;
use Nexus\AmlCompliance\Contracts\TransactionMonitorInterface;

public function __construct(
    private readonly TransactionMonitorInterface $transactionMonitor
) {}

// Monitor transaction
$result = $this->transactionMonitor->monitorTransaction(
    transactionId: 'tx-67890',
    amount: Money::of(50000, 'USD'),
    fromPartyId: 'party-12345',
    toPartyId: 'party-67890',
    transactionDate: new \DateTimeImmutable()
);

if ($result->isSuspicious()) {
    $suspicionReasons = $result->getReasons();
    // ['velocity_anomaly', 'amount_threshold_exceeded', 'high_risk_jurisdiction']
}

SAR Generation

use Nexus\AmlCompliance\Services\SarGenerator;
use Nexus\AmlCompliance\Contracts\SarGeneratorInterface;

public function __construct(
    private readonly SarGeneratorInterface $sarGenerator
) {}

// Generate SAR
$sar = $this->sarGenerator->generateSar(
    partyId: 'party-12345',
    reason: 'Unusual transaction patterns detected',
    suspiciousActivities: [
        'Multiple transactions just below $10,000 threshold',
        'Transactions with high-risk jurisdictions',
    ],
    amount: Money::of(45000, 'USD')
);

// SAR includes: SAR ID, party details, activity description, compliance officer assignment

Architecture

Atomic Package Compliance

This package adheres to ARCHITECTURE.md atomicity principles:

Domain-Specific: ONE domain - AML risk assessment & transaction monitoring
Stateless: No in-memory state, all data externalized via repositories
Framework-Agnostic: Pure PHP 8.3+, zero framework coupling
Logic-Focused: Business rules only, no migrations/controllers
Contract-Driven: All dependencies injected as interfaces
Independently Deployable: Published to Packagist independently

Package Structure

packages/AmlCompliance/
├── composer.json
├── README.md
├── REQUIREMENTS.md
├── LICENSE
├── .gitignore
└── src/
    ├── Contracts/           # Interfaces
    │   ├── AmlRiskAssessorInterface.php
    │   ├── TransactionMonitorInterface.php
    │   ├── SarGeneratorInterface.php
    │   └── AmlRepositoryInterface.php
    ├── Services/            # Business logic
    │   ├── AmlRiskAssessor.php
    │   ├── TransactionMonitor.php
    │   └── SarGenerator.php
    ├── ValueObjects/        # Immutable domain objects
    │   ├── AmlRiskScore.php
    │   ├── RiskFactors.php
    │   ├── TransactionMonitoringResult.php
    │   └── SuspiciousActivityReport.php
    ├── Enums/               # Status enums
    │   ├── RiskLevel.php
    │   ├── JurisdictionRisk.php
    │   └── BusinessTypeRisk.php
    └── Exceptions/          # Domain exceptions
        ├── AmlException.php
        └── RiskAssessmentFailedException.php

Key Interfaces

AmlRiskAssessorInterface

interface AmlRiskAssessorInterface
{
    /**
     * Assess AML risk for a party
     * 
     * @return AmlRiskScore Risk score (0-100) with factor breakdown
     */
    public function assessParty(string $partyId): AmlRiskScore;
    
    /**
     * Reassess risk for all parties above threshold
     */
    public function reassessHighRiskParties(int $threshold = 70): array;
}

TransactionMonitorInterface

interface TransactionMonitorInterface
{
    /**
     * Monitor transaction for suspicious patterns
     */
    public function monitorTransaction(
        string $transactionId,
        Money $amount,
        string $fromPartyId,
        string $toPartyId,
        \DateTimeImmutable $transactionDate
    ): TransactionMonitoringResult;
}

SarGeneratorInterface

interface SarGeneratorInterface
{
    /**
     * Generate Suspicious Activity Report
     */
    public function generateSar(
        string $partyId,
        string $reason,
        array $suspiciousActivities,
        Money $amount
    ): SuspiciousActivityReport;
}

Risk Scoring Formula

Overall AML Risk Score (0-100)

AML Risk Score = 
    (Jurisdiction Risk × 0.30) +
    (Business Type Risk × 0.20) +
    (Sanctions Match × 0.25) +
    (Transaction Patterns × 0.25)

Risk Factors

Factor	Weight	Description
Jurisdiction Risk	30%	Country risk level (high-risk jurisdictions)
Business Type Risk	20%	Industry risk (MSB, cryptocurrency, gambling)
Sanctions Match	25%	Sanctions/PEP screening results
Transaction Patterns	25%	Unusual transaction patterns (velocity, structuring)

Risk Level Thresholds

Score Range	Risk Level	Action Required
0-39	LOW	Standard monitoring
40-69	MEDIUM	Enhanced due diligence
70-100	HIGH	SAR filing, account freeze

Dependencies

azaharizaman/nexus-party - Party identity management
azaharizaman/nexus-sanctions - Sanctions screening results for risk scoring
psr/log - PSR-3 logging interface

Testing

Run unit tests:

composer test

Integration Example (Laravel)

// app/Providers/AmlServiceProvider.php
use Nexus\AmlCompliance\Contracts\AmlRiskAssessorInterface;
use App\Repositories\Aml\EloquentAmlRepository;

$this->app->singleton(AmlRiskAssessorInterface::class, function ($app) {
    return new AmlRiskAssessor(
        repository: new EloquentAmlRepository(),
        sanctionsScreener: $app->make(SanctionsScreenerInterface::class),
        logger: $app->make(LoggerInterface::class)
    );
});

Use Cases

Financial Services

Customer risk assessment during onboarding
Transaction monitoring for unusual patterns
SAR filing automation
Enhanced due diligence triggers

Cryptocurrency Exchanges

High-risk jurisdiction detection
Structuring detection (transactions just below reporting thresholds)
Velocity anomaly detection

Money Service Businesses (MSBs)

Continuous risk monitoring
Automated SAR generation
Compliance officer alerts

Related Packages

azaharizaman/nexus-sanctions - Regulatory screening (used for risk scoring)
azaharizaman/nexus-kyc-verification - Identity verification
azaharizaman/nexus-party-compliance - Comprehensive party compliance orchestration

License

MIT License. See LICENSE file for details.

Support

Documentation: REQUIREMENTS.md
Issues: GitHub Issues
Email: support@nexus-erp.com

Last Updated: December 16, 2025
Maintained By: Nexus Compliance Team

azaharizaman / nexus-aml-compliance

Maintainers

Package info

Statistics

Security