Feat/aml monitoring

[Kenlachy]

AML Transaction Monitoring with Case Management Workflow

Overview

Implements regulatory compliance AML transaction monitoring with configurable rules (velocity, structuring, geo-mismatch) and a case-management workflow for analysts to review flagged events.

Implementation Details

Core Components

• Rule Engine (src/aml/ruleEvaluator.ts)

  • Evaluates transactions against 4 rule types: velocity, structuring, geo-mismatch, amount threshold
  • Context-aware evaluation using historical transaction data
  • Supports configurable thresholds and time windows

• Rule Management (src/aml/amlRuleRepository.ts)

  • Semver versioning for all rule changes (major.minor.patch)
  • Complete version history in aml_rule_version_history table
  • Rollback capability to any previous version
  • Config changes trigger minor version bumps
  • Enable/disable changes trigger patch version bumps

• Alert Management (src/aml/amlAlertRepository.ts)

  • Stores alerts generated from rule triggers
  • Links alerts to investigation cases
  • Tracks alert lifecycle: pending → reviewed → dismissed

• Case Management (src/aml/amlAlertRepository.ts)

  • Workflow for analyst investigation
  • Status tracking: open → assigned → investigating → closed/dismissed
  • Disposition tracking: confirmed_suspicious, false_positive, inconclusive, legitimate

• Service Layer (src/aml/amlService.ts)

  • Orchestrates all AML operations
  • Integrated audit logging for compliance
  • Transaction evaluation pipeline

• REST API (src/routes/amlRoutes.ts)

  • Rule management endpoints (CRUD, rollback, history)
  • Case management endpoints (create, assign, close)
  • Alert management endpoints (pending, investor, dismiss)
  • Zod validation for all inputs

Database Schema

Created 4 new tables in src/db/migrations/001_aml_tables.sql:

• aml_rules - Rule definitions with semver versioning
• aml_rule_version_history - Complete audit trail for rule changes
• aml_alerts - Alerts generated from rule triggers
• aml_cases - Investigation cases for analyst workflow

All tables include proper indexes for performance and audit compliance.

Investment Pipeline Integration

Hooked AML evaluator into post-investment pipeline in src/services/investmentService.ts:

• AML evaluation runs asynchronously after investment creation
• Non-blocking design - investment creation succeeds even if AML evaluation fails
• Errors are logged but don't prevent investment flow
• Ensures system availability while maintaining monitoring

Security & Compliance

Rule Versioning

• All rule changes are versioned using semver
• Complete version history maintained for audit trails
• Rollback capability to any historical version

Audit Logging

• All rule changes logged with user ID and reason
• All case operations logged with full context
• All alert creations logged as security violations
• Audit logs are immutable and tamper-evident

Access Control

• Rule management requires admin privileges
• Case management requires analyst privileges
• Alert dismissal requires justification
• All operations are authenticated and authorized

Data Privacy

• Investor PII protected at rest and in transit
• Alert details contain minimal necessary information
• Case notes are access-controlled
• Historical data retention follows regulatory requirements

Testing

Test Coverage

Comprehensive test suite with 89 tests (all passing):

Rule Evaluator Tests (src/aml/ruleEvaluator.test.ts) - 14 tests

• Velocity rule triggers (count and amount thresholds)
• Structuring detection (transaction splitting)
• Geo-mismatch detection (country inconsistencies)
• Amount threshold detection
• Multi-rule evaluation
• Edge cases (disabled rules, unknown types, failed transactions)

AML Service Tests (src/aml/amlService.test.ts) - 16 tests

• Transaction evaluation and alert creation
• Rule CRUD operations with versioning
• Version history tracking and rollback
• Case management workflow
• Alert lifecycle management
• Audit logging verification

AML Rule Repository Tests (src/aml/amlRuleRepository.test.ts) - 16 tests

• Rule creation with initial version 1.0.0
• Rule retrieval (by ID, enabled, all)
• Rule updates with version bumping
• Version history tracking
• Rollback to previous versions
• Error handling for nonexistent resources

AML Alert Repository Tests (src/aml/amlAlertRepository.test.ts) - 17 tests

• Alert creation and retrieval
• Alert status updates
• Case creation and workflow
• Case status transitions
• Alert-to-case linking
• Error handling for edge cases

AML Routes Tests (src/routes/amlRoutes.test.ts) - 26 tests

• Rule management endpoints (GET, POST, PUT, rollback)
• Case management endpoints (GET, POST, PUT)
• Alert management endpoints (GET, dismiss)
• Input validation with Zod
• Error handling and status codes

Coverage Metrics

• AML module overall: 92.55% line coverage
• AMLRuleRepository: 97.77% coverage
• AMLAlertRepository: 92.2% coverage
• AMLService: 88.88% coverage
• RuleEvaluator: 88.52% coverage
• AMLRoutes: 79.36% coverage

Running Tests

closes #431

npm test -- --testPathPatterns="aml"