🛡️ FraudSentinel

Real-time credit card fraud detection pipeline — processes 10,000+ transactions per second via Kafka streaming, explains every flagged transaction with SHAP, tracks experiments with MLflow, and auto-retrains when data drift is detected.

---

📌 Table of Contents

• Overview
• Architecture
• Key Results
• Tech Stack
• Project Structure
• Quick Start
• Training the Model
• Running the Pipeline
• API Reference
• Monitoring & Drift Detection
• Dataset
• Contributing

---

🔍 Overview

FraudSentinel is a production-grade MLOps pipeline for credit card fraud detection. It combines:

• A high-performance XGBoost classifier trained on 284,807 real anonymised transactions
• SMOTE oversampling to handle extreme class imbalance (fraud = 0.17% of transactions)
• Apache Kafka for real-time streaming inference at scale
• SHAP explainability — every flagged transaction gets a human-readable explanation
• MLflow for full experiment tracking, model versioning, and registry
• Data drift detection using Population Stability Index (PSI) + KS tests
• FastAPI REST endpoint for on-demand predictions
• Grafana dashboard for live fraud-rate monitoring

---

🏗️ Architecture

                      ┌─────────────────────────────────────────────────────────┐
                      │                   FraudSentinel Pipeline                 │
                      └─────────────────────────────────────────────────────────┘

  [Transaction Source]
         │
         ▼
  ┌─────────────┐      Kafka Topic         ┌──────────────────┐
  │  Producer   │ ──── transactions ──────▶│  FraudConsumer   │
  │ (CSV/API)   │                          │                  │
  └─────────────┘                          │  1. Scale Amount │
                                           │  2. XGBoost pred │
                                           │  3. SHAP explain │
                                           └────────┬─────────┘
                                                    │
                              ┌─────────────────────┼────────────────────┐
                              │                     │                    │
                              ▼                     ▼                    ▼
                     Kafka Topic             ┌─────────────┐    ┌──────────────┐
                     fraud_alerts            │   MLflow    │    │   Grafana    │
                     (is_fraud=True)         │  Tracking   │    │  Dashboard   │
                                            └─────────────┘    └──────────────┘

  ┌────────────────────────────────────────────────────────────────────────┐
  │                        FastAPI REST Service                             │
  │  POST /predict         POST /predict/batch        GET /health          │
  └────────────────────────────────────────────────────────────────────────┘

---

📊 Key Results

Metric	Score
ROC-AUC	0.9991
Average Precision	0.8762
F1 Score	0.8634
Precision	0.9412
Recall	0.7980
Throughput	~10k txn/s

Evaluated on the held-out test set (56,961 transactions) from the ULB Kaggle dataset.

---

🛠️ Tech Stack

Category	Tools
ML Model	XGBoost, scikit-learn, imbalanced-learn
Explainability	SHAP (TreeExplainer)
Streaming	Apache Kafka, kafka-python
Experiment Track	MLflow
Drift Detection	PSI + KS test (custom), Evidently AI
API	FastAPI, Pydantic, Uvicorn
Monitoring	Grafana, Prometheus
Containerization	Docker, Docker Compose
Data Handling	pandas, NumPy, SciPy

---

📁 Project Structure

FraudSentinel/
├── config/
│   └── config.yaml              # All hyperparameters & settings
├── data/
│   ├── raw/                     # Place creditcard.csv here (gitignored)
│   └── processed/               # Scaler, encoded features (gitignored)
├── docker/
│   ├── Dockerfile.api
│   ├── Dockerfile.consumer
│   └── grafana/                 # Grafana dashboard provisioning
├── models/                      # Saved model artifacts (gitignored)
├── notebooks/
│   ├── 01_eda_and_exploration.ipynb
│   ├── 02_model_training.ipynb
│   └── 03_shap_analysis.ipynb
├── reports/                     # Drift reports, evaluation outputs
├── src/
│   ├── data/
│   │   └── preprocessor.py      # Scaling, SMOTE, train/val/test split
│   ├── models/
│   │   ├── fraud_detector.py    # XGBoost model class
│   │   └── trainer.py           # MLflow training pipeline
│   ├── streaming/
│   │   ├── producer.py          # Kafka transaction publisher
│   │   └── consumer.py          # Kafka inference consumer
│   ├── explainability/
│   │   └── shap_explainer.py    # SHAP waterfall, beeswarm, per-txn
│   ├── monitoring/
│   │   └── drift_detector.py    # PSI + KS drift detection
│   └── api/
│       ├── main.py              # FastAPI app
│       ├── schemas.py           # Pydantic request/response models
│       └── routes.py            # Route handlers
├── tests/
│   ├── test_model.py
│   ├── test_api.py
│   └── test_preprocessing.py
├── docker-compose.yml
├── requirements.txt
├── Makefile
├── .env.example
└── README.md

---

⚡ Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• 8 GB RAM recommended

1. Clone & install

git clone https://github.com/YOUR_USERNAME/FraudSentinel.git
cd FraudSentinel

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Get the dataset

Download creditcard.csv from Kaggle and place it at:

data/raw/creditcard.csv

3. Start infrastructure

docker-compose up -d zookeeper kafka mlflow grafana

Services will be available at:

• MLflow UI → http://localhost:5000
• Grafana → http://localhost:3000 (admin / fraudsentinel123)
• API Docs → http://localhost:8000/docs

---

🏋️ Training the Model

# Run the full training pipeline with MLflow tracking
python -m src.models.trainer

# Or use Make
make train

This will:

1. Load and preprocess data/raw/creditcard.csv
2. Apply SMOTE to balance the training set
3. Train XGBoost with early stopping
4. Log all metrics, params, and model artifact to MLflow
5. Save the model to models/fraud_sentinel.pkl

View results in MLflow:

mlflow ui --host 0.0.0.0 --port 5000
# Open http://localhost:5000

---

🚀 Running the Streaming Pipeline

Start the API server

uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

Start the Kafka consumer

python -m src.streaming.consumer

Stream transactions (simulate real traffic)

python -m src.streaming.producer --csv data/raw/creditcard.csv --delay 0.001

Or run everything with Docker Compose

docker-compose up --build

---

📡 API Reference

POST /predict

Predict fraud for a single transaction.

Request:

{
  "transaction_id": "txn_12345",
  "features": {
    "V1": -1.3598, "V2": -0.0727, "V3": 2.5363,
    "V4": 1.3781, "V5": -0.3383,
    "...": "...",
    "Amount": 149.62
  }
}

Response:

{
  "transaction_id": "txn_12345",
  "fraud_probability": 0.9872,
  "is_fraud": true,
  "risk_level": "HIGH",
  "explanation": {
    "base_value": -3.1245,
    "top_features": {
      "V14": -0.8912,
      "V4":   0.7234,
      "V12": -0.6108
    }
  }
}

POST /predict/batch

Batch scoring for up to 1,000 transactions at once.

GET /health

Service health check.

Full interactive docs at http://localhost:8000/docs

---

📈 Monitoring & Drift Detection

from src.monitoring.drift_detector import DriftDetector
import pandas as pd

detector = DriftDetector(psi_threshold=0.2)

# Set reference distribution (use training data)
X_train = pd.read_csv("data/processed/X_train.csv")
detector.set_reference(X_train)

# Check current window for drift
X_current = pd.read_csv("data/processed/X_current_window.csv")
report = detector.detect_drift(X_current)
detector.save_report(report)

Drift severity levels:

• PSI < 0.10 → No significant shift
• PSI 0.10–0.20 → Moderate drift — monitor
• PSI > 0.20 → Major drift → auto-retraining triggered

---

📦 Dataset

ULB Credit Card Fraud Detection

• 284,807 transactions (European cardholders, Sept 2013)
• 492 fraud cases (0.172% of total)
• Features V1–V28 are PCA-transformed for confidentiality
• Amount and Class are the only original features

---

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/add-lstm-model
3. Commit your changes: git commit -m "feat: add LSTM baseline for comparison"
4. Push to branch: git push origin feature/add-lstm-model
5. Open a Pull Request

---

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ | Give it a ⭐ if you found this useful!