feat(aml): add configurable AML screening service with velocity checks

[Faromzy]

feat(aml): Configurable AML Screening Service with Velocity Checks

Summary

Implements a synchronous AML screening service that evaluates every payment transaction against
configurable rules before processing begins. Flagged transactions are automatically set to
pending_review status and cannot be processed until a compliance officer approves them.

Rules are stored in the database — no code deployment needed to tune thresholds, add
blacklisted numbers, or toggle rules on/off.

Changes

Database

• New aml_rules table — stores rule definitions (type, JSONB config, enabled flag)
• New aml_screening_results table — one audit row per transaction × rule evaluation, regardless
  of whether it triggered
• Seeded 5 default rules out of the box:
  • Large transaction threshold (≥ 1,000,000 XAF)
  • Elevated amount alert (≥ 500,000 XAF)
  • Hourly velocity check (> 3 transactions from same phone in 1 hr)
  • Daily velocity check (> 10 transactions from same phone in 24 hrs)
  • Phone number blacklist

New Files

• src/services/amlScreening.ts — core screening engine with 1-min DB rule cache, Redis velocity
  counters (time-bucketed keys shared across instances), and fail-open behavior on Redis
  unavailability
• src/models/amlScreeningResult.ts — data access layer for aml_screening_results
• src/services/tests/amlScreening.test.ts — 32 unit tests, all passing
• migrations/20260630_create_aml_screening_tables.sql

Modified

• src/controllers/transactionController.ts — screening now runs synchronously inside
  processTransactionRequest before transactionModel.create():
  • Flagged → status: review, tags [aml-screened, aml-flagged], admin note with matched rule
    names
  • Clean → status: pending, tag [aml-screened]
  • Velocity counters incremented after successful transaction commit
• Result rows persisted with the real transaction ID (fire-and-forget, never blocks the payment
  path)

Test Coverage

32 unit tests covering:

• All 3 rule types (amount threshold, velocity check, blacklisted phone)
• Invalid rule configs (graceful no-trigger)
• Redis unavailability (fail-open — transaction proceeds)
• DB persistence failure isolation (never propagates to caller)
• Rule cache and invalidateRuleCache()
• Velocity counter TTL logic (set only on first increment)
• Combined multi-rule OR semantics

Notes

Pre-commit hook failures are pre-existing environment issues on main (spdy/http_parser missing
native module, sharp binary not installed for this runtime). Unrelated to this PR.
closes #11

[drips-wave]

@Faromzy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits