payguard-poc/QUICKSTART.md

PayGuard Quick Start Guide

This guide will get you up and running with the PayGuard fraud detection demo in minutes.

Prerequisites

• Docker Desktop (includes Docker and Docker Compose)
• Python 3.9 or higher (python3 --version)
• pip (usually comes with Python)

Step 1: Clone and Navigate

cd /path/to/payguard-poc

Step 2: Create Virtual Environment

python3 -m venv venv
source venv/bin/activate              # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

This installs:

• fastapi (web framework)
• uvicorn (API server)
• python-jose (JWT authentication)
• kafka-python (message broker client)
• redis (cache client)
• pybreaker (circuit breaker pattern)
• numpy (numerical computing)

Step 4: Start Infrastructure

In one terminal, run:

docker compose up -d

Verify services are running:

docker compose ps

You should see:

• ✓ zookeeper
• ✓ kafka
• ✓ redis

Step 5: Open 4 Terminal Windows

Terminal 1: API Server

source venv/bin/activate
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000

Terminal 2: Fraud Detection Consumer

source venv/bin/activate
cd consumer
python pipeline.py

Expected output:

[INFO] PayGuard Fraud Detection Consumer - INITIALIZATION
[INFO] Waiting for transactions...

Terminal 3: Run Demo

source venv/bin/activate
python producer/simulate.py

Watch Terminal 2 to see transactions flowing through the pipeline!

Terminal 4: Query Results (Optional)

redis-cli

Then:

> KEYS result:*          # See all results
> GET result:<tx_id>     # View specific result
> HGETALL user:*         # See user profiles

Understanding Output

Watch Terminal 2 (consumer) to see the pipeline in action:

Normal Transaction

[STEP 1/6] Feature Extraction & Behavioral Profiling
[FEATURE EXTRACTION] features=[75.50, 100.00, 1, 0.5]

[STEP 2/6] Layer 1 - Fast Model Scoring
[LAYER 1 SCORING] Fraud probability: 0.0500 → LOW RISK, fast-track approval

[DECISION] ✓ APPROVED (Layer 1 score 0.0500 < 0.4 threshold)

Suspicious Transaction

[STEP 1/6] Feature Extraction & Behavioral Profiling
[FEATURE EXTRACTION] features=[8500.00, 100.00, 2, 0.5]

[STEP 2/6] Layer 1 - Fast Model Scoring
[LAYER 1 SCORING] Fraud probability: 0.9500 → SUSPICIOUS, escalate to Layer 2

[STEP 3/6] Behavioral Anomaly Detection
[ANOMALY] Amount/Avg Ratio: 85.00x
[ANOMALY] ⚠ Significant deviation detected (>3.0x)

[STEP 4/6] Layer 2 - Deep Model Scoring
[LAYER 2 SCORING] Fraud probability: 0.9500 → BLOCK (high confidence in fraud)

[DECISION] ✗ BLOCKED (Layer 2 score 0.9500 > 0.7 threshold)

Key Concepts Demonstrated

Fast Path (95% of transactions)

• Transaction comes in → Layer 1 quick check → Approve immediately
• Low-risk transactions bypass expensive deep analysis
• Result: Sub-100ms latency

Suspicious Path (5% of transactions)

• Layer 1 flags as suspicious → Behavioral profiling → Layer 2 deep analysis
• Only worthy transactions pay the cost of intensive processing
• Higher accuracy but slower (200-500ms)

Circuit Breaker

If Layer 2 becomes unavailable:

• System doesn't crash
• Falls back to conservative estimate using Layer 1
• Message: "Layer 2 unavailable, using conservative fallback"

Behavioral Profiling

• User spends $100 on average
• Transaction for $8500 is 85x normal amount
• → HIGH RISK → Deep analysis
• Profile updates after each transaction

Clean Up

When you're done:

# Stop containers (keep data)
docker compose stop

# Or remove everything
docker compose down

# Deactivate virtual environment
deactivate

Troubleshooting

Docker issues

docker compose logs kafka    # Check Kafka logs
docker compose logs redis    # Check Redis logs

API not responding

curl http://localhost:8000/health    # Should return {"status": "healthy", ...}

Python import errors

# Make sure venv is activated
which python    # Should point to venv/bin/python
pip list        # Should show fastapi, redis, kafka-python, etc.

Kafka connection issues

docker compose exec kafka kafka-broker-api-versions --bootstrap-server localhost:9092

Redis not working

redis-cli ping    # Should return PONG

Next Steps

Once comfortable with the basic demo:

1. Read the architecture docs: See README_IMPLEMENTATION.md for deep dive
2. Modify scenarios: Edit producer/simulate.py to test custom transactions
3. Adjust thresholds: Change 0.4/0.7 scores in consumer/pipeline.py
4. Study the patterns: Each component demonstrates a design pattern

Quick Reference

Goal	Command
Start all services	docker compose up -d
Start API	uvicorn api.main:app --reload
Start consumer	cd consumer && python pipeline.py
Send test transactions	python producer/simulate.py
Check results	redis-cli → KEYS result:*
View logs	docker compose logs -f kafka
Stop all	docker compose down
Clean everything	docker compose down -v

---

Need help? Check README_IMPLEMENTATION.md for architectural details and troubleshooting.