payguard-poc/FRAUD_DETECTION_DEMO.md

# PayGuard Fraud Detection - Complete Demo Guide

## System Overview

The PayGuard system is a **6-step fraud detection pipeline** that analyzes transactions in real-time:

```
Transaction Submitted → Feature Extraction → ML Layer 1 → ML Layer 2 → Decision Engine → Risk Assessment → Results Stored
```

## Prerequisites

All services must be running:

```bash
docker compose up -d --build
```

Verify with:
```bash
docker compose ps
```

All 5 services should show as "Up":
- zookeeper
- kafka
- redis
- api (fastapi)
- frontend (react)

## How the Demo Works

### 1. User Submits Transaction via Frontend

The React frontend at `http://localhost:3000` collects:
- User ID (auto-generated)
- Token (JWT authentication)
- Transaction details (amount, merchant, description)

### 2. API Validates & Publishes to Kafka

The FastAPI backend:
- Validates JWT token
- Checks transaction format
- Publishes message to Kafka topic: `transactions`
- Returns: `{"status": "accepted", "transaction_id": "..."}`

### 3. Consumer Listens & Processes

The consumer pipeline:
- Subscribes to Kafka `transactions` topic
- Processes each message through 6-step pipeline
- Stores results in Redis

### 4. ML Models Score Fraud Risk

The pipeline runs two layers of ML models:
- **Layer 1**: Initial risk scoring
- **Layer 2**: Refined prediction

Decision outcomes:
- **APPROVED** (score < 0.3) - Legitimate transaction
- **REVIEW** (score 0.3-0.7) - Borderline, needs human review
- **FRAUD_DETECTED** (score > 0.7) - High fraud risk, block

## Complete Demo Walkthrough

### Step 1: Start Services (if not running)

```bash
# Terminal 1: Ensure Docker services are running
cd /Users/pat/Projects/PAT/payguard-poc
docker compose up -d --build
```

### Step 2: Start the Consumer Pipeline

```bash
# Terminal 2: Run the fraud detection consumer
cd /Users/pat/Projects/PAT/payguard-poc
cd consumer
python3 pipeline.py
```

You should see:
```
2026-04-24 21:25:19,338 [INFO] ================================================================================
2026-04-24 21:25:19,338 [INFO] PayGuard Fraud Detection Consumer - INITIALIZATION
2026-04-24 21:25:19,338 [INFO] ================================================================================
2026-04-24 21:25:19,339 [INFO] [FEATURE EXTRACTOR] Initialized, redis=localhost:6379
2026-04-24 21:25:19,400 [INFO] [DECISION ENGINE] Initialized with circuit breaker
2026-04-24 21:25:19,450 [INFO] [CONSUMER] Listening on topic: transactions
```

### Step 3: Open Frontend

```
http://localhost:3000
```

You'll see the PayGuard transaction submission form.

### Step 4: Generate Initial Token

Click **"Generate Token"** button

You should see:
- Green message: "Token generated successfully"
- JWT token displayed (starts with `eyJh...`)
- Token Type: "bearer"

### Step 5: Submit Test Transactions

Submit these transactions in sequence to demonstrate different fraud detection scenarios:

#### Scenario 1: Normal Transaction (LEGITIMATE)

```
Amount: 75.50
Merchant: Starbucks Coffee
Description: Morning coffee purchase
```

**Expected Result:**
```
API Response: 200 OK
{
  "status": "accepted",
  "transaction_id": "txn_abc123",
  "message": "Transaction accepted"
}

Consumer Output:
[INFO] Processing transaction: txn_abc123
[INFO] Amount: $75.50 | Merchant: Starbucks | Features: NORMAL
[INFO] Layer 1 Score: 0.15
[INFO] Layer 2 Score: 0.12
[INFO] Decision: APPROVED (Score: 0.12)
[INFO] Risk Level: LOW
[INFO] Result stored in Redis
```

#### Scenario 2: High-Value Transaction (SUSPICIOUS)

```
Amount: 5000.00
Merchant: Electronics Store
Description: Laptop purchase
```

**Expected Result:**
```
API Response: 200 OK
{
  "status": "accepted",
  "transaction_id": "txn_def456",
  ...
}

Consumer Output:
[INFO] Processing transaction: txn_def456
[INFO] Amount: $5000.00 | Merchant: Electronics | Features: HIGH_AMOUNT
[INFO] Layer 1 Score: 0.68
[INFO] Layer 2 Score: 0.72
[INFO] Decision: FRAUD_DETECTED (Score: 0.72)
[INFO] Risk Level: HIGH
[INFO] Result stored in Redis
[WARNING] Transaction flagged for review
```

#### Scenario 3: Rapid Successive Transactions (VELOCITY FRAUD)

Submit these 3 transactions quickly (within 60 seconds):

```
Transaction 1:
Amount: 200.00
Merchant: Best Buy
Description: Computer monitor

Transaction 2 (10 seconds later):
Amount: 300.00
Merchant: Amazon
Description: Keyboard

Transaction 3 (20 seconds later):
Amount: 250.00
Merchant: Target
Description: Office supplies
```

**Expected Result:**
```
Consumer Output for Transaction 2:
[INFO] Processing transaction: txn_ghi789
[INFO] Features: NORMAL
[INFO] Layer 1 Score: 0.25
[INFO] Layer 2 Score: 0.28
[INFO] Decision: APPROVED

Consumer Output for Transaction 3:
[INFO] Processing transaction: txn_jkl012
[INFO] Features: VELOCITY_FRAUD (3 transactions in 60 seconds)
[INFO] Layer 1 Score: 0.75
[INFO] Layer 2 Score: 0.81
[INFO] Decision: FRAUD_DETECTED
[INFO] Risk Level: HIGH
[INFO] Reason: Unusual transaction velocity
```

#### Scenario 4: Unusual Geographic Pattern (if supported)

```
Amount: 2000.00
Merchant: International Hotel (different country)
Description: Hotel booking
```

**Expected Result:**
```
Consumer Output:
[INFO] Processing transaction: txn_mno345
[INFO] Features: GEOGRAPHIC_ANOMALY
[INFO] Layer 1 Score: 0.65
[INFO] Layer 2 Score: 0.70
[INFO] Decision: FRAUD_DETECTED (borderline)
[INFO] Risk Level: HIGH
```

## Understanding Consumer Output

When the consumer processes a transaction, look for:

### Processing Log Format
```
[TIMESTAMP] [LOG_LEVEL] [COMPONENT] Message
```

### Key Components
- `[FEATURE EXTRACTOR]` - Analyzing transaction features
- `[MODEL SCORER]` - Running ML models
- `[DECISION ENGINE]` - Making fraud/legitimate decision
- `[RESULT STORAGE]` - Saving to Redis

### Risk Scores

The ML models produce a fraud risk score from 0.0 to 1.0:

```
0.0 - 0.3  = APPROVED (Safe transaction)
0.3 - 0.7  = REVIEW (Borderline, needs human review)
0.7 - 1.0  = FRAUD_DETECTED (Block transaction)
```

### What Triggers Fraud Detection

The models detect:

1. **Unusual Amount** - Spike from typical spending
2. **Velocity Fraud** - Too many transactions too quickly
3. **Merchant Category Mismatch** - Wrong type of store for user
4. **Time-Based Anomaly** - Transaction at unusual hour
5. **Geographic Inconsistency** - Impossible travel between locations
6. **Behavioral Change** - Deviation from user's normal patterns

## Checking Results in Redis

Optional: View the results stored in Redis:

```bash
# Terminal 3: Connect to Redis
redis-cli -p 6379

# List all stored transactions
> KEYS *

# View a specific transaction result
> GET transaction:txn_abc123
> GET transaction:txn_def456

# View all keys
> SCAN 0

# Exit
> exit
```

Expected Redis data format:
```json
{
  "transaction_id": "txn_abc123",
  "user_id": "user_xyz",
  "amount": 75.50,
  "merchant": "Starbucks Coffee",
  "fraud_score": 0.12,
  "decision": "APPROVED",
  "risk_level": "LOW",
  "timestamp": "2026-04-24T21:30:00Z",
  "features": {
    "amount_std_dev": 0.8,
    "velocity": 0.1,
    "geographic_score": 0.0
  }
}
```

## Complete Demo Timeline

**Duration: ~10 minutes**

```
0:00 - Start Docker services (docker compose up)
1:00 - Consumer pipeline listening
2:00 - Open http://localhost:3000
2:30 - Generate token
3:00 - Submit normal transaction ($75.50)
3:30 - Consumer processes, shows APPROVED
4:00 - Submit high-value transaction ($5000)
4:30 - Consumer processes, shows FRAUD_DETECTED
5:00 - Submit 3 rapid transactions
6:00 - Consumer detects velocity fraud on 3rd
6:30 - Explain results and scoring
7:00 - Check Redis for stored results
8:00 - Show architecture and data flow
```

## Troubleshooting

### Consumer Won't Start
```bash
# Make sure you're in the right directory
cd /Users/pat/Projects/PAT/payguard-poc
python3 -m pip install --break-system-packages kafka-python
python3 consumer/pipeline.py
```

### API Returns 503 Error
```bash
# Check Kafka is running
docker compose logs kafka | tail -20

# Restart if needed
docker compose restart kafka
```

### No Consumer Output
```bash
# Check consumer logs
docker compose logs api | tail -20

# Verify Kafka is receiving messages
docker compose exec kafka kafka-console-consumer \
  --bootstrap-server kafka:29092 \
  --topic transactions \
  --from-beginning
```

### Frontend Shows CORS Error
Already fixed - but if you see it:
```bash
# Rebuild API with CORS
docker compose up -d --build api
```

## Architecture Diagram

```
┌─────────────────────────────────────────────────────┐
│ Browser: http://localhost:3000                      │
│ ┌───────────────────────────────────────────────┐   │
│ │ React Frontend                                │   │
│ │ - Generate Token (JWT)                        │   │
│ │ - Submit Transactions                         │   │
│ │ - Display Status (200 OK / 503)               │   │
│ └─────────────┬─────────────────────────────────┘   │
└───────────────┼─────────────────────────────────────┘
                │ HTTP + CORS
                ↓
    ┌─────────────────────────────────────┐
    │ API: http://localhost:8000          │
    │ ┌─────────────────────────────────┐ │
    │ │ FastAPI Backend                 │ │
    │ │ - JWT Validation                │ │
    │ │ - Transaction Validation        │ │
    │ │ - Kafka Publishing              │ │
    │ └──────────┬──────────────────────┘ │
    └───────────┼────────────────────────┘
                │ TCP to kafka:29092
                ↓
    ┌─────────────────────────────────────┐
    │ Kafka: localhost:9092 (external)    │
    │ Internal: kafka:29092               │
    │ Topic: transactions                 │
    └──────────┬────────────────────────┘
               │
      ┌────────┴──────────┬────────────┐
      │                   │            │
      ↓                   ↓            ↓
  ┌─────────┐        ┌────────┐   ┌──────────┐
  │ Consumer│        │ Redis  │   │ Zookeeper│
  │Pipeline │        │ Cache  │   │ Coord    │
  │(6 steps)│        │        │   │          │
  └────┬────┘        └────────┘   └──────────┘
       │
   ML Models
   Decision
   Results
```

## What This Demonstrates

✅ **End-to-End Architecture**
- Frontend to API communication
- CORS cross-origin requests
- Kafka async messaging
- Docker containerization

✅ **Fraud Detection**
- Feature extraction from transactions
- Machine learning model scoring
- Decision engine logic
- Risk assessment

✅ **Real-Time Processing**
- Immediate transaction acceptance
- Async consumer processing
- Live logging of decisions
- Redis result persistence

✅ **Scalability**
- Kafka can handle high throughput
- Consumer can be scaled horizontally
- Stateless API design
- Distributed architecture

## Next Steps

After the demo:
1. Modify transaction amounts to see different fraud scores
2. Submit transactions during "off-hours" to test time-based detection
3. Check Redis for all stored decisions
4. Review consumer logs for detailed scoring
5. Examine the 6-step pipeline in `consumer/pipeline.py`

---

**Ready to demonstrate?** Start with Step 1 above!