RailHawk

Real-time ML fraud detection across payment rails — UPI · AEPS · DMT · Cards · Loans.
P95 < 100ms · RBI + PCI-DSS compliant · BC agent fraud detection · Apache 2.0

---

Documentation

Document	Description
Architecture	3-layer decision engine, feature store tiers, latency budget, Kafka feedback loop
Feature Catalog	466 features across 9 layers, Redis key schema, training-serving parity
Model Reference	All 6 L2 models, ensemble diversity rationale, Meta-learner
Training Guide	7-phase pipeline, temporal splits, Optuna HPO, evaluation gates, MLflow
API Reference	Endpoint schemas, auth, client_id BaaS field, error codes, latency SLAs
Compliance	PCI-DSS, RBI, Aadhaar Act §29, data localisation, chargeback feedback
Operations	Docker stack, deployment, monitoring, runbooks
Data Sources	Schema, synthetic generator, external datasets, cleaning

---

System Overview

POST /v1/transaction/score  (< 100ms P95)
          │
          ▼
┌─────────────────────────────────────────────┐
│  LAYER 1: RULES ENGINE  (< 1ms)             │
│  YAML hotpatch · blocklist · velocity        │
│  HARD_BLOCK → return immediately             │
└──────────────────┬──────────────────────────┘
                   │ PASS
     ┌──────┬──────┼──────┬──────┬──────┐
     ▼      ▼      ▼      ▼      ▼      ▼   asyncio.gather (6 parallel)
┌────────┐┌─────┐┌──────┐┌────┐┌────┐┌───────────┐
│LightGBM││ XGB ││CatBst││LSTM││ AE ││IsoForest  │
│per-rail││opt. ││opt.  ││ONNX││legit││ONNX (opt.)│
│TreeSHAP││~5ms ││~5ms  ││~6ms││~4ms││~3ms       │
└───┬────┘└──┬──┘└──┬───┘└─┬──┘└─┬──┘└───┬───────┘
    └────────┴───────┴──────┴─────┴───────┘
                         │ 6 scores (opt. fall back to lgbm/ae)
                         ▼
┌─────────────────────────────────────────────┐
│  LAYER 3: META-LEARNER  (< 2ms)             │
│  LR stacking → Isotonic calibration         │
│  risk_score 0–1000 → ALLOW/REVIEW/BLOCK     │
└─────────────────────────────────────────────┘
          │
          ├─── Background: SHAP + audit → PostgreSQL
          ├─── Background: GNN ring detection (async)
          └─── Kafka: chargebacks → confirmed_fraud labels → retrain

---

Quick Start

Prerequisites

• Python 3.11+
• Docker 24+ and Docker Compose v2
• Redis 7.2, PostgreSQL 16 (via Docker)

Option A — Pre-trained weights (fastest)

git clone https://github.com/coderguy-07/Railhawk.git && cd Railhawk
pip install -e ".[dev]"
docker compose -f infra/docker/docker-compose.yml up -d

# Download pre-trained weights (synthetic data, v0.6.0)
python scripts/bootstrap.py --version v0.6.0

# Start API
uvicorn api.main:app --reload

Pre-trained weights are built on synthetic data. For production use, train on your own labeled dataset.

Option B — Train from scratch

# 1. Clone and install
git clone https://github.com/coderguy-07/Railhawk.git && cd Railhawk
pip install -e ".[dev]"

# 2. Start infrastructure
docker compose -f infra/docker/docker-compose.yml up -d

# 3. Generate synthetic training data (~1M transactions)
python -m src.data.generator \
  --n_transactions 1000000 \
  --output data/synthetic/txns.parquet \
  --seed 42

# 4. Train all models (7-phase pipeline, GPU recommended)
python -m src.training.trainer \
  --config configs/model_config.yaml

# 5. Verify health
curl http://localhost:8000/health/ready

# 6. Score a transaction
curl -X POST http://localhost:8000/v1/transaction/score \
  -H "Authorization: Bearer dev_key_1" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_test_001",
    "timestamp_utc": "2026-07-30T10:00:00Z",
    "rail": "upi",
    "channel": "upi_push",
    "amount_inr": "5000.00",
    "currency_code": "INR",
    "customer_id_hash": "a1b2c3d4e5f6...",
    "merchant_id": "merch_001",
    "merchant_country": "IN",
    "vpa_sender_hash": "abc123...",
    "vpa_receiver_hash": "def456..."
  }'

---

Per-Rail Model Stack

Rail	Primary GBM	Sequence	Anomaly	Key Fraud Patterns
UPI	LightGBM-UPI	LSTM-15txn	Autoencoder	SIM swap, phishing QR, screen share
AEPS	LightGBM-AEPS	—	Biometric AE	Ghost txn, rogue agent, fingerprint clone
DMT	LightGBM-DMT	LSTM-10txn	IsoForest	Mule accounts, structuring ₹97K–99K
Cards	LightGBM-Cards	LSTM-20txn	Autoencoder	CNP, BIN attack, skimming

---

Performance Targets

Metric	Target	Alert Threshold
Fraud catch rate	≥ 75%	< 70% → P1
False positive rate	≤ 2%	> 2.5% → P2
Fraud amount caught	≥ 80% ₹	< 74% → P1
P95 API latency	< 100ms	> 100ms → P1
Model AUC-PR	> 0.85	< 0.80 → retrain
Score PSI	< 0.10	> 0.20 → retrain

---

Project Structure

fraud_detection/
├── src/
│   ├── data/           # Schema, generator, loader, cleaner
│   ├── features/       # 9-layer feature pipeline + Redis store
│   ├── models/         # LightGBM, XGBoost, CatBoost, LSTM, AE, IsoForest, GNN, ensemble
│   ├── training/       # 7-phase trainer, splitter, evaluator, Optuna optimizer
│   ├── inference/      # Parallel predictor + model protocols
│   ├── cross_rail/     # Unified risk store + propagator
│   └── monitoring/     # PSI drift detector, alerting, agent monitor
├── api/
│   ├── main.py         # FastAPI app with lifespan model loading
│   └── routes/         # /v1/transaction/score, /health/*
├── kafka/
│   └── chargeback_consumer.py  # Kafka → confirmed_fraud label feedback loop
├── configs/
│   └── fraud_rules.yaml  # YAML hotpatch rules (reload on SIGHUP)
├── infra/
│   ├── docker/         # Multi-stage Dockerfile + docker-compose
│   ├── postgres/       # Schema + migrations (001: WORM, 002: xgb/catboost/client_id)
│   └── prometheus/     # Scrape config + alert rules
├── docs/               # This documentation
├── tests/
│   ├── unit/
│   ├── integration/
│   └── load/           # k6 latency SLA tests
└── notebooks/          # EDA, feature exploration, evaluation

---

Tech Stack

Layer	Library	Version
ML — tabular	lightgbm	≥ 4.3
ML — sequence	pytorch + onnxruntime	≥ 2.3 / ≥ 1.18
ML — graph	torch-geometric	≥ 2.5
HPO	optuna	≥ 3.6
Serving	fastapi + uvicorn[uvloop]	≥ 0.111
Feature store	redis[asyncio]	≥ 5.0
Database	asyncpg	≥ 0.29
Experiment tracking	mlflow	≥ 2.15
Drift monitoring	evidently	≥ 0.4
Observability	prometheus-client + structlog	latest

See requirements.txt for pinned versions.

---

Compliance Summary

• PCI-DSS: No raw PAN in any feature, log, or artifact. card_token (tokenized), bin_8, pan_last4 only.
• Aadhaar Act §29: Raw biometric never stored or processed. AEPS uses UIDAI-returned quality metadata (match score, attempt count, session duration) only.
• RBI: 8-year audit retention (PMLA), 3-year SHAP retention (customer dispute window), quarterly FRMC model review.
• Data localisation: All compute and storage in ap-south-1 (India).

See Compliance for full details.