Getting Started

Get the fraud detection platform running locally in under 5 minutes.

Prerequisites

• Docker and Docker Compose
• Python 3.11+ (for dashboard)
• Git

Quick Start

1. Clone and Setup

git clone https://github.com/udaytamma/FraudDetection.git
cd FraudDetection

# Copy environment template
cp .env.example .env

2. Start Infrastructure

docker-compose up -d

This starts:

• Redis (port 6379) - Velocity counters
• PostgreSQL (port 5432) - Evidence storage
• Prometheus (port 9090) - Metrics collection

3. Start the API

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the API
uvicorn src.api.main:app --reload --port 8000

4. Verify Installation

# Health check
curl http://localhost:8000/health

# Expected response:
{
  "status": "healthy",
  "redis": "connected",
  "postgres": "connected",
  "policy_version": "1.0"
}

Your First Payment Fraud Check

Send a test SIM activation transaction:

curl -X POST http://localhost:8000/decide \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_001",
    "idempotency_key": "idem_001",
    "amount_cents": 2500,
    "currency": "USD",
    "service_id": "mobile_prepaid_001",
    "service_type": "mobile",
    "event_subtype": "sim_activation",
    "card_token": "card_abc",
    "user_id": "subscriber_456",
    "phone_number": "15551234567",
    "imei": "353456789012345"
  }'

Response:

{
  "transaction_id": "txn_001",
  "decision": "ALLOW",
  "scores": {
    "risk_score": 0.15,
    "criminal_score": 0.0,
    "friendly_fraud_score": 0.0,
    "card_testing_score": 0.0,
    "velocity_score": 0.0
  },
  "reasons": [],
  "processing_time_ms": 6.07,
  "policy_version": "2.0.0"
}

Test Attack Scenarios

Card Testing Attack (Small Topups)

curl -X POST http://localhost:8000/decide \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_002",
    "idempotency_key": "idem_002",
    "amount_cents": 500,
    "currency": "USD",
    "service_id": "mobile_prepaid_001",
    "service_type": "mobile",
    "event_subtype": "topup",
    "card_token": "card_testing_attacker",
    "user_id": "attacker_001",
    "geo": {
      "ip_address": "45.33.32.156",
      "is_datacenter": true
    }
  }'

Expected: REVIEW or BLOCK decision with card_testing signal.

SIM Farm Attack (Emulator)

curl -X POST http://localhost:8000/decide \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_003",
    "idempotency_key": "idem_003",
    "amount_cents": 0,
    "currency": "USD",
    "service_id": "mobile_prepaid_001",
    "service_type": "mobile",
    "event_subtype": "sim_activation",
    "card_token": "card_sim_farm",
    "user_id": "sim_farmer",
    "device": {
      "device_id": "emulator_001",
      "is_emulator": true
    },
    "geo": {
      "ip_address": "10.0.0.1",
      "is_tor": true
    }
  }'

Expected: BLOCK decision with bot_emulator signal (SIM farm indicator).

Start the Dashboard

For visual testing with the demo dashboard:

streamlit run dashboard.py --server.port 8501

Open http://localhost:8501 to access the interactive testing interface.

Service Ports Summary

Next Steps

• Architecture - Understand the system design
• API Reference - Complete endpoint documentation
• Demo Dashboard - Interactive testing guide