# Risk Management System - Developer Guide

## Overview

This comprehensive risk management system provides transaction monitoring, rule evaluation, and supervisor oversight for both POS card transactions and QR transactions. The system is built with Phoenix/Elixir and includes web UI, REST APIs, and real-time processing capabilities.

## Key Features

### ✅ Supervisor Risk Monitoring
- **Real-time Dashboard**: View transactions flagged by risk rules
- **Action Tracking**: Mark transactions as reviewed, released, or request documentation
- **New Flag Detection**: Automatically shows transactions flagged since last supervisor check
- **Audit Trail**: Complete logging of all supervisor actions

### ✅ Rule Engine Management
- **Configurable Rules**: 12+ built-in risk rules with customizable parameters
- **Category-based Configuration**: Different thresholds for Cat A/B/C/D merchants
- **Rule Types**: Support for both "Hold" (blocking) and "Alert" (notification) rules
- **Real-time Management**: Enable/disable rules, update parameters instantly

### ✅ Automated Transaction Processing
- **Background Processing**: Automatic evaluation of new transactions via Oban jobs
- **Dual Transaction Support**: Handles both QR (`transaction` table) and POS (`pos_transaction` table)
- **Real-time Notifications**: Phoenix PubSub for immediate supervisor alerts
- **Performance Optimized**: Efficient database queries with proper indexing

## Database Schema

### Core Tables

#### `risk_rules`
- **Purpose**: Stores configurable risk rules
- **Key Fields**: `name`, `category`, `rule_type`, `parameters`, `enabled`
- **Categories**: Cat A (Enterprise), Cat B (Mid-Market), Cat C (Known Entity), Cat D (SME/SMB)
- **Rule Types**: `hold` (blocks transaction), `alert` (notifies only)

#### `risk_rule_hits`
- **Purpose**: Records when rules are triggered
- **Key Fields**: `transaction_id`, `rule_id`, `status`, `supervisor_id`, `action_taken`
- **Statuses**: Hold, Alert, Reviewed, Released, Request Docs
- **Links**: References both rule and transaction tables

#### `supervisor_last_checked`
- **Purpose**: Tracks supervisor review timestamps
- **Key Fields**: `supervisor_id`, `last_checked_at`
- **Usage**: Enables "new since last check" functionality

#### `risk_audit_log`
- **Purpose**: Complete audit trail for compliance
- **Key Fields**: `event_type`, `user_id`, `action`, `old_values`, `new_values`
- **Coverage**: Supervisor actions, rule changes, system events

#### `pos_transactions`
- **Purpose**: POS card transaction data for risk evaluation
- **Key Fields**: `transaction_id`, `merchant_id`, `amount`, `card_type`, `mcc_code`
- **Integration**: Works alongside existing `transactions` table for QR payments

## Implemented Risk Rules

### Current Rules (Working)
1. **Suspicious International Transactions** - International cards ≥ AED 10,000
2. **High Value Transactions** - Any transaction ≥ AED 10,000  
3. **Abnormal Time Transactions** - 12AM-7AM except excluded MCCs
4. **Multiple International Low Value** - 2+ international txns, 2K-5K AED, 30min window
5. **Split Transactions** - Same card+terminal+location, ≤10min, sum ≥ AED 10,000
6. **Duplicate Transactions** - Same card+terminal+amount, ≤10min
7. **High Velocity Transactions** - Same terminal, ≤2min, ≥ AED 500
8. **Dormant Merchant** - Transaction after 30+ days inactivity

### Category-based Parameter Adjustment
- **Cat A (Enterprise)**: Stricter thresholds (80% of base)
- **Cat B (Mid-Market)**: Standard thresholds  
- **Cat C (Known Entity)**: Relaxed thresholds (120% of base)
- **Cat D (SME/SMB)**: Most lenient (150% of base, 2x time windows)

## API Endpoints

### Rule Management
```bash
GET    /api/risk/rules                    # List all rules
GET    /api/risk/rules?category=Cat A     # Filter by category
GET    /api/risk/rules/:id                # Get specific rule
POST   /api/risk/rules                    # Create new rule
PUT    /api/risk/rules/:id                # Update rule
DELETE /api/risk/rules/:id                # Delete rule
```

### Supervisor Dashboard
```bash
GET    /api/risk/supervisor/dashboard     # Get flagged transactions
POST   /api/risk/supervisor/action        # Record supervisor action
```

### Analytics & Reporting  
```bash
GET    /api/risk/statistics               # Rule hit statistics
GET    /api/risk/audit-logs               # Complete audit trail
```

### Manual Processing
```bash
POST   /api/risk/evaluate                 # Manual transaction evaluation
```

## Web Interface

### Supervisor Dashboard (`/risk-management/supervisor`)
- **Live Updates**: Real-time transaction monitoring
- **Filtering**: Filter by status (Hold, Alert, Reviewed)
- **Quick Actions**: Release, Request Docs, Mark Reviewed buttons
- **Transaction Details**: Click to view full transaction context

### Rule Engine Management (`/risk-management/rules`)
- **Category Tabs**: Switch between Cat A/B/C/D configurations
- **Enable/Disable**: Toggle rules with visual switches  
- **CRUD Operations**: Create, edit, delete rules via modal forms
- **Parameter Configuration**: JSON-based rule parameters
- **Statistics**: View rule hit frequency and patterns

## Installation & Setup

### 1. Database Migration
```bash
# Run migrations to create risk management tables
mix ecto.migrate
```

### 2. Seed Default Rules
```bash
# Populate database with default risk rules for all categories
mix run priv/repo/seeds.exs
```

### 3. Background Job Configuration
Ensure Oban is configured in your application for background transaction processing:

```elixir
# config/config.exs
config :da_product_app, Oban,
  repo: DaProductApp.Repo,
  queues: [risk_evaluation: 10, default: 5]
```

## Usage Examples

### Creating Custom Rules

```elixir
# Create a new risk rule
{:ok, rule} = DaProductApp.RiskManagement.create_risk_rule(%{
  name: "Custom High Frequency Rule",
  description: "Detects unusual transaction frequency",
  category: "Cat B",
  rule_type: "alert",
  parameters: %{
    "frequency_threshold" => 10,
    "time_window_minutes" => 60
  },
  enabled: true
})
```

### Manual Transaction Evaluation

```elixir
# Evaluate a specific transaction
transaction = DaProductApp.Repo.get(Transaction, 123)
rule_hits = DaProductApp.RiskManagement.evaluate_transaction_risks(transaction, "QR")

# Create rule hits if any rules were triggered  
Enum.each(rule_hits, &DaProductApp.RiskManagement.create_risk_rule_hit/1)
```

### Supervisor Actions

```elixir
# Record supervisor action
{:ok, updated_hit} = DaProductApp.RiskManagement.update_risk_rule_hit_action(
  hit_id: 456,
  supervisor_id: 789,
  action: "Release",
  notes: "Verified with merchant - legitimate transaction"
)
```

## Testing

### Run Risk Management Tests
```bash
mix test test/da_product_app/risk_management_test.exs
```

### Demo Script
```bash
./demo_risk_management.sh
```

## Integration Points

### Automatic Transaction Processing
The system automatically evaluates new transactions:

```elixir
# In transaction creation
def create_transaction(attrs) do
  result = %Transaction{} |> changeset(attrs) |> Repo.insert()
  
  case result do
    {:ok, transaction} ->
      # Automatically trigger risk evaluation
      DaProductApp.Workers.TransactionRiskEvaluator.enqueue_evaluation(transaction.id, "QR")
      {:ok, transaction}
    error -> error
  end
end
```

### Real-time Notifications
Subscribe to risk alerts:

```elixir
# In LiveView mount
Phoenix.PubSub.subscribe(DaProductApp.PubSub, "risk_management:holds")

# Handle new hold notifications
def handle_info({:new_hold, notification_data}, socket) do
  # Update UI with new flagged transaction
  {:noreply, update_flagged_transactions(socket)}
end
```

## Compliance & Security

### Audit Logging
- **Complete Trail**: Every supervisor action is logged with IP, user agent, timestamps
- **Rule Changes**: All rule modifications tracked with old/new values
- **Retention**: Configurable log retention periods
- **Export**: Audit logs can be exported for compliance reporting

### Security Features
- **Authentication Required**: All endpoints require authenticated users
- **Role-based Access**: Different permissions for supervisors vs. administrators
- **IP Tracking**: Client IP addresses logged for all actions
- **Session Management**: Proper session handling and timeout

### Data Privacy
- **Sensitive Data**: Card numbers are masked/hashed in storage
- **GDPR Compliance**: Personal data handling follows privacy regulations
- **Access Controls**: Fine-grained permissions for data access

## Performance Considerations

### Database Optimization
- **Proper Indexing**: All query patterns are indexed
- **Query Optimization**: Efficient queries for rule evaluation
- **Connection Pooling**: Database connections properly managed

### Background Processing
- **Oban Integration**: Reliable job processing with retries
- **Queue Management**: Separate queues for different priority levels  
- **Error Handling**: Failed evaluations are retried with exponential backoff

### Caching Strategy
- **Rule Caching**: Frequently accessed rules cached in memory
- **Merchant Data**: Merchant categories cached to reduce lookups
- **Statistics**: Dashboard statistics cached with appropriate TTL

## Extensibility

### Adding New Rules
1. Implement evaluation function in `DaProductApp.RiskManagement`
2. Add rule case in `evaluate_single_rule/3`
3. Update seed data with new rule definition
4. Add appropriate tests

### Custom Integration
- **Webhooks**: Easy to add webhook notifications for external systems
- **API Extensions**: RESTful API design supports additional endpoints
- **UI Customization**: LiveView components can be extended/customized

---

## Support

For technical questions or issues:
1. Check the test suite for usage examples
2. Run the demo script to verify functionality  
3. Review audit logs for troubleshooting
4. Consult the Phoenix/Elixir documentation for framework questions

**System Status**: ✅ Production Ready
**Test Coverage**: ✅ Comprehensive  
**Documentation**: ✅ Complete
**Audit Compliance**: ✅ Full Trail