Add comprehensive fraud detection demo guide
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
1 parent
81129056a0
commit
e9ddebeda2
1 file changed
+447
@@ -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!
|
||||
Reference in new issue
Block a user