# AML Screening Flow

## Overview

The AML/CTF screening system performs comprehensive transaction monitoring, sanctions checking, PEP (Politically Exposed Person) detection, and pattern analysis to identify potential money laundering or terrorist financing activities. This flow documents the complete screening and risk scoring process.

## Prerequisites

- Transaction exists with entity information
- AML service operational
- Sanctions lists available
- PEP database accessible
- RegTech supervision engine available

## Visual Flow Diagram

```
┌─────────────┐
│ Transaction │
│  Request    │
└──────┬──────┘
       │
       │ 1. Sanctions Check
       ▼
┌─────────────────────────┐
│ Check Sanctions List    │
│  - Entity name lookup    │
│  - OFAC, EU, UN lists    │
│  - Risk: +100 if match   │
└──────┬──────────────────┘
       │
       │ 2. PEP Check
       ▼
┌─────────────────────────┐
│ Check PEP List          │
│  - Entity name lookup    │
│  - PEP database          │
│  - Risk: +50 if match    │
└──────┬──────────────────┘
       │
       │ 3. Pattern Detection
       ▼
┌─────────────────────────┐
│ Detect Anomalous        │
│  Patterns                │
│  - Velocity analysis     │
│  - Circular transfers    │
│  - Risk score            │
└──────┬──────────────────┘
       │
       │ 4. AML Behavior Monitoring
       ▼
┌─────────────────────────┐
│ RegTech AML Behavior    │
│  Monitoring              │
│  - Rule evaluation       │
│  - Critical behaviors    │
│  - Risk: +50 per critical│
└──────┬──────────────────┘
       │
       │ 5. Calculate Risk Score
       ▼
┌─────────────────────────┐
│ Determine Status        │
│  - CLEAR: < 50          │
│  - FLAGGED: 50-99        │
│  - BLOCKED: >= 100       │
└──────┬──────────────────┘
       │
       │ 6. Create Record
       ▼
┌─────────────┐
│ Compliance  │
│  Record     │
└─────────────┘
```

## Step-by-Step Process

### Step 1: Sanctions Screening
1. Receive screening request with:
   - Sovereign bank ID
   - Transaction ID
   - Entity name (optional)
   - Entity type (optional)
2. Initialize risk score: `0`
3. Initialize screening results object
4. If entity name provided:
   - Check sanctions lists:
     - OFAC (Office of Foreign Assets Control)
     - EU sanctions list
     - UN sanctions list
   - Query sanctions database
   - If match found:
     - Set `sanctionsMatch: true` in results
     - Add risk score: `+100` (critical match)
5. Store sanctions check result

**Code Reference**: `src/core/compliance/aml.service.ts:19-82`

### Step 2: PEP Screening
1. If entity name provided:
   - Check PEP (Politically Exposed Person) database
   - Query PEP list by entity name
   - If match found:
     - Set `pepMatch: true` in results
     - Add risk score: `+50` (high risk)
2. Store PEP check result

**Code Reference**: `src/core/compliance/aml.service.ts:37-44`

### Step 3: Pattern Detection
1. Analyze transaction for anomalous patterns:
   - Transaction velocity (frequency)
   - Amount patterns
   - Geographic patterns
   - Time-based patterns
2. Detect specific patterns:
   - Circular transfers (money going in circles)
   - Synthetic layering (complex transaction chains)
   - Structuring (breaking large amounts into smaller)
   - Rapid movement (velocity anomalies)
3. Calculate pattern risk score:
   - Each pattern adds to risk score
   - Pattern severity determines weight
4. Store pattern risk in results

**Code Reference**: `src/core/compliance/aml.service.ts:46-49`

### Step 4: AML Behavior Monitoring
1. Call RegTech supervision engine:
   - Pass transaction ID
   - Pass sovereign bank ID
   - Request AML behavior monitoring
2. Supervision engine evaluates AML rules:
   - Retrieves active AML behavior rules
   - Evaluates each rule against transaction
   - Returns triggered behaviors
3. Process behavior results:
   - Filter critical behaviors (severity: `critical`)
   - For each critical behavior:
     - Add risk score: `+50`
   - Store all behaviors in results
4. Store AML behavior results

**Code Reference**: 
- `src/core/compliance/aml.service.ts:51-57`
- `src/core/compliance/regtech/supervision-engine.service.ts:22-50`

### Step 5: Risk Score Calculation
1. Sum all risk components:
   - Sanctions match: `+100` (if match)
   - PEP match: `+50` (if match)
   - Pattern risk: variable
   - Critical AML behaviors: `+50` each
2. Total risk score = sum of all components

### Step 6: Status Determination
1. Determine compliance status based on risk score:
   - **CLEAR**: Risk score < 50
   - **FLAGGED**: Risk score >= 50 and < 100
   - **BLOCKED**: Risk score >= 100
2. Status thresholds:
   - `AML_RISK_CRITICAL`: 100
   - `AML_RISK_HIGH`: 50

**Code Reference**: `src/core/compliance/aml.service.ts:59-65`

### Step 7: Create Compliance Record
1. Create compliance record in database:
   - Sovereign bank ID
   - Transaction ID
   - Record type: `AML_CHECK`
   - Entity name (if provided)
   - Entity type (if provided)
   - Risk score
   - Status (CLEAR, FLAGGED, or BLOCKED)
   - Screening result (all check results)
   - Timestamp
2. Return compliance record

**Code Reference**: `src/core/compliance/aml.service.ts:67-82`

## Error Handling

### Error: Transaction Not Found
- **Detection**: Transaction ID doesn't exist
- **Action**: Continue screening with available data
- **Recovery**: Verify transaction ID

### Error: Sanctions Database Unavailable
- **Detection**: Cannot query sanctions list
- **Action**: Log warning, continue with other checks
- **Recovery**: Retry sanctions check, use cached data

### Error: RegTech Engine Unavailable
- **Detection**: Supervision engine returns error
- **Action**: Log warning, continue without AML behavior check
- **Recovery**: Retry AML behavior monitoring

### Error: Pattern Detection Failure
- **Detection**: Pattern analysis throws error
- **Action**: Set pattern risk to 0, continue
- **Recovery**: Investigate pattern detection service

## Integration Points

### Related Services
- **AML Service**: `src/core/compliance/aml.service.ts`
- **Supervision Engine**: `src/core/compliance/regtech/supervision-engine.service.ts`
- **Sanctions Database**: External sanctions lists (OFAC, EU, UN)
- **PEP Database**: External PEP database

### API Endpoints
- `POST /api/v1/compliance/aml/screen` - Screen transaction
- `GET /api/v1/compliance/aml/:recordId` - Get screening record
- `GET /api/v1/compliance/aml/transactions/:transactionId` - Get transaction screening

### Database Models
- `ComplianceRecord` - Compliance screening records
- `SanctionsList` - Sanctions list entries
- `SupervisionRule` - AML behavior rules

## Performance Metrics

- **Sanctions Check**: < 50ms target
- **PEP Check**: < 50ms target
- **Pattern Detection**: < 100ms target
- **AML Behavior Monitoring**: < 200ms target
- **Total End-to-End**: < 400ms target
- **Throughput**: 10,000+ screenings/second
- **Availability**: 99.99% uptime target

## Security Considerations

### Data Privacy
- Entity information handled securely
- Screening results encrypted
- Access restricted to authorized personnel

### Real-Time Screening
- Screening performed before transaction execution
- Blocked transactions prevented from processing
- Flagged transactions require review

### Audit Trail
- All screening results logged
- Risk scores recorded
- Status changes tracked

## Testing Scenarios

### Happy Path - CLEAR
1. Valid transaction
2. No sanctions match
3. No PEP match
4. No anomalous patterns
5. No critical AML behaviors
6. Risk score < 50
7. Status: CLEAR

### Happy Path - FLAGGED
1. Valid transaction
2. PEP match found
3. Risk score >= 50 and < 100
4. Status: FLAGGED
5. Requires review

### Happy Path - BLOCKED
1. Valid transaction
2. Sanctions match found
3. Risk score >= 100
4. Status: BLOCKED
5. Transaction prevented

### Error Scenarios
1. Transaction not found
2. Sanctions database unavailable
3. RegTech engine unavailable
4. Pattern detection failure

### Edge Cases
1. Multiple sanctions matches
2. Both PEP and sanctions match
3. Multiple critical AML behaviors
4. High pattern risk score
5. Concurrent screenings for same transaction

---

**Related Flows**:
- [Identity Verification Flow](./identity-verification-flow.md)
- [KYC Enforcement Flow](./kyc-enforcement-flow.md)
- [RegTech Monitoring Flow](./regtech-monitoring-flow.md)

