fraud-shield

End-to-end fraud detection pipeline for financial transactions — built for real-world fintech constraints.

---

Overview

fraud-shield is a machine learning system for detecting fraudulent financial transactions, simulating the architecture and constraints of a real-world banking or fintech environment.

The project goes beyond model training — it is designed as a production-minded end-to-end pipeline: from raw transaction data to interpretable, trackable predictions, following the same engineering principles used in deployed fraud systems.

---

Problem Statement

Financial fraud is a rare but high-impact event. Standard accuracy metrics fail here. The system is specifically designed to handle:

• Severe class imbalance — fraud represents ~0.1% of transactions, making naive models useless
• High cost of false negatives — missed fraud has direct financial consequences
• Interpretability requirements — decisions must be explainable and auditable
• Scalability — the pipeline is structured to extend to streaming or batch production workloads

---

Approach

The problem is framed as a binary supervised classification task with the following design decisions:

Concern	Strategy
Class imbalance	Class weighting + threshold tuning
Evaluation	Precision-Recall on fraud class as primary metric
Reproducibility	MLflow experiment tracking
Threshold optimization	Precision-Recall curve analysis on test set

---

Feature Engineering

Raw PaySim features are transformed before modeling:

Transformation	Rationale
balance_diff_orig = oldbalanceOrg - newbalanceOrig	Captures account drain — strongest fraud signal
balance_diff_dest = newbalanceDest - oldbalanceDest	Captures destination account behavior
is_high_risk_type (TRANSFER/CASH_OUT = 1)	Fraud only occurs in these two transaction types
log1p(amount, balance_diff_*)	Compresses heavy-tailed distributions
Drop oldbalanceOrg, newbalanceOrig, oldbalanceDest, newbalanceDest	Replaced by diff features (correlation > 0.99)
Drop isFlaggedFraud, nameOrig, nameDest	Near-constant or high-cardinality ID columns

---

Model

Model	Role
LightGBM	Primary model
Logistic Regression	Linear baseline

KNN and tree ensembles were discarded due to computational constraints with 6M+ rows. All runs are logged in MLflow.

---

Results

Threshold optimized at 0.99 via Precision-Recall curve analysis on the test set.

Metric	Value
ROC-AUC	0.998
Precision (fraud)	0.84
Recall (fraud)	0.77
F1 (fraud)	0.80
Accuracy	0.9996

Accuracy is reported for completeness but is not the optimization target — the dataset is highly imbalanced.

---

Evaluation Metrics

Given the imbalanced nature of fraud detection, accuracy is deliberately excluded as the primary metric.

• Precision-Recall curve ← threshold selection
• Recall (fraud detection sensitivity)
• Precision (false alarm control)
• F1-score (fraud class)
• ROC-AUC

---

Dataset

PaySim — Mobile Money Simulator

A synthetic dataset simulating mobile money transactions based on real logs from a financial service provider. ~6.3M transactions, ~0.1% fraud. Includes transaction type, amount, origin/destination balances, and ground-truth fraud labels.

---

Project Structure

fraud_shield/
├── data/
│   ├── raw/                  ← original data (never modified)
│   ├── interim/              ← intermediate processing
│   └── processed/            ← model-ready data
│
├── models/
│   └── artifacts/            ← encoders, scalers, saved models (.joblib)
│
├── notebooks/
│   ├── 0-0-DescargaDatos.ipynb
│   ├── 0-1-ProcesamientoDatos.ipynb
│   └── 0-2-Ejecucion.ipynb
│
├── reports/
│   └── figures/              ← generated plots and evaluation charts
│
├── fraud_shield/
│   ├── data/                 make_dataset.py
│   ├── features/             build_features.py
│   ├── models/               train_model.py · predict_model.py
│   ├── visualization/        visualize.py
│   └── utils/                paths.py
│
├── tests/
├── main.py                   ← full pipeline entry point
├── Makefile
└── pyproject.toml

---

Quick Start

# 1. Install dependencies
make setup

# 2. Activate environment
source .venv/bin/activate

# 3. Place data in data/raw/ and configure DATA_FILE / TARGET_COL in main.py

# 4. Explore notebooks
invoke lab

# 5. Run full pipeline
python main.py

See the ayuda file for additional configuration details.

---

Design Philosophy

This project is built with a production mindset:

• Feature engineering grounded in domain knowledge — balance differentials as primary fraud signals
• Threshold optimization decoupled from training — allows business-driven tradeoff adjustment without retraining
• Modular pipeline design — each stage is independently testable
• Experiment reproducibility through MLflow tracking
• Evaluation strategy tuned to fraud-specific business costs

The goal is a fraud detection system blueprint — extensible into a production-ready solution for fintech or banking environments.