pat/payguard-poc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive fraud detection demo guide

Browse Source 
Created FRAUD_DETECTION_DEMO.md with complete walkthrough:

- System overview and how the 6-step pipeline works
- Prerequisites and setup verification
- Step-by-step demo walkthrough (10 minutes)
- 4 fraud detection scenarios:
  1. Normal transaction (APPROVED)
  2. High-value transaction (FRAUD_DETECTED)
  3. Velocity fraud - rapid transactions (FRAUD_DETECTED)
  4. Geographic anomaly (FRAUD_DETECTED)

- Expected output for each scenario
- Consumer log interpretation guide
- Fraud risk score meanings (0.0-1.0)
- What triggers fraud detection
- Redis result inspection
- Architecture diagram
- Troubleshooting guide
- Demo timeline (10 minutes)

This guide enables anyone to demonstrate the complete fraud detection
system with realistic test scenarios and clear explanations of results.

Co-authored-by: Copilot <[email protected]>
This commit is contained in:
John Patrick TeruelandCopilot committed 2026-04-24 21:26:19 +08:00
1 parent 81129056a0
commit e9ddebeda2
1 file changed
+447
Download Patch File Download Diff File Expand all files Collapse all files
FRAUD_DETECTION_DEMO.md
+447
View File
@@ -0,0 +1,447 @@
# 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!