FraudShield AI: Enterprise Financial Fraud Detection Platform

A comprehensive Machine Learning system and intelligence dashboard designed for high-throughput, real-time transaction surveillance, anomaly detection, and capital risk mitigation.

Executive Summary
Technology Stack Architecture (Mermaid)
The Financial Fraud Challenge
System Architecture & Data Flow (Mermaid)
Dataset Specifications & Schema
Data Cleansing & Ingestion Pipeline
Feature Engineering & Mathematical Formulations
Exploratory Data Analysis & Risk Patterns
Machine Learning Model Architecture
Quantitative Performance Benchmarks & Validation
Real-Time Inference & Automated Decision Routing (Mermaid)
Enterprise Sky Blue Intelligence Dashboard
CLI Pipeline Orchestration (main.py)
Installation & Operational Setup
REST API Integration Schema
Production Deployment & Containerization
Security, Governance & Compliance
Project Directory Hierarchy
Troubleshooting & Frequently Asked Questions

1. Executive Summary

Financial fraud is an existential operational threat for modern payment networks, commercial banks, and digital commerce ecosystems. FraudShield AI is an end-to-end, production-grade intelligence solution engineered to evaluate, classify, and intercept fraudulent transactions in sub-5ms latency.

Core System Accomplishments

Overall Accuracy: 93.53% across 50,000 audited transactions.
Precision on Fraud Class: 99.68%, maintaining a false alert rate of just 0.12% to eliminate checkout friction for legitimate customers.
Fraud Capture Recall: 80.11%, intercepting 12,871 fraudulent events and preventing millions in capital drainage.
ROC-AUC Score: 0.9787, providing near-ideal class separation across risk probability thresholds.
Decision Latency: < 5ms per transaction scoring cycle.

2. Technology Stack Architecture

The FraudShield AI platform is built upon a modern, decoupled open-source Python data science and machine learning ecosystem:

flowchart TB
    subgraph INGESTION["Data Ingestion & Processing Layer"]
        PANDAS["Pandas (v2.0+) - Data Manipulation & Wrangling"]
        NUMPY["NumPy (v1.24+) - Vectorized Math Computations"]
        PATHLIB["Pathlib - Deterministic Cross-Platform File Paths"]
    end

    subgraph ML_CORE["Machine Learning & Inference Engine"]
        SKLEARN["Scikit-Learn (v1.3+) - Ensemble Classifier Engine"]
        RF["RandomForestClassifier (300 Estimators, Balanced Class Weights)"]
        SCALER["StandardScaler - Z-Score Feature Normalization"]
        JOBLIB["Joblib (v1.3+) - Model Artifact Serialization & Loading"]
    end

    subgraph VISUALIZATION["Visualization & Analytics Tier"]
        PLOTLY["Plotly (v5.18+) - Interactive Light Sky Blue Charts & Gauges"]
        SEABORN["Seaborn (v0.12+) - High-Resolution Statistical Visualizations"]
        MATPLOTLIB["Matplotlib (v3.7+) - 300 DPI Export Plotting"]
    end

    subgraph PRESENTATION["Presentation & Interface Tier"]
        STREAMLIT["Streamlit (v1.28+) - Multi-Page Enterprise Intelligence App"]
        CSS3["Custom CSS3 - Sky Blue Glassmorphism & Animated Cards"]
        REST_API["REST API Specification - JSON Payload Validation"]
    end

    INGESTION --> ML_CORE
    ML_CORE --> VISUALIZATION
    VISUALIZATION --> PRESENTATION
    ML_CORE --> PRESENTATION

3. The Financial Fraud Challenge

Traditional financial defense mechanisms rely heavily on static, rule-based heuristics (such as IF transaction_amount > $500 THEN flag). These legacy frameworks introduce critical institutional vulnerabilities:

High False Positive Rates: Rigid thresholds decline high-value transactions from VIP or legitimate users, damaging customer retention.
Inability to Detect Evolving Patterns: Coordinated fraud syndicates adapt to static thresholds via card velocity testing, rapid micro-transactions, and distributed device spoofing.
Operational Overhead: Manual review queues become bottlenecked, delaying transaction settlement.

FraudShield AI transitions the defense posture from reactive rule lists to proactive Ensemble Machine Learning, capturing non-linear cross-feature relationships between account liquidity, transaction velocity, geographic anomalies, and device metadata.

4. System Architecture & Data Flow

flowchart TD
    RAW["Raw Ingestion Stream<br/>(data/raw/synthetic_fraud_dataset1.csv)"]
    
    subgraph STEP1["1. Data Cleansing (src/data_cleaning.py)"]
        DEDUP["Deduplication"]
        PARSE["Datetime Normalization"]
        PURGE["Null / Corrupt Record Purge"]
    end

    subgraph STEP2["2. Feature Engineering (src/feature_engineering.py)"]
        TEMP["Temporal Decomposition (Year, Month, Day, DayOfWeek)"]
        RATIO["Amount-to-Balance Liquidity Ratio"]
        FLAGS["Velocity Flags (High Amount, High Frequency)"]
        OHE["One-Hot Categorical Encoding (29 Dimensions)"]
    end

    subgraph STEP3["3. Modeling & Training (src/train_model.py)"]
        SPLIT["Stratified 80/20 Train-Test Split"]
        NORM["StandardScaler Normalization"]
        TRAIN["Random Forest Ensemble (300 Trees)"]
        SAVE["Export Artifacts (models/*.pkl)"]
    end

    subgraph STEP4["4. Validation & Intelligence (src/evaluate_model.py)"]
        REPORT["Evaluation Report (reports/model_evaluation.txt)"]
        METRICS["Metrics (Accuracy, Precision, Recall, ROC-AUC)"]
    end

    subgraph STEP5["5. Dashboard & Decision Interface (dashboard/app.py)"]
        PORTAL["Overview Landing Portal"]
        SIM["Real-Time Risk Simulator"]
        ANALYTICS["3D Feature Space Analytics"]
        BATCH["Batch Forensic Auditor"]
    end

    RAW --> STEP1
    STEP1 --> STEP2
    STEP2 --> STEP3
    STEP3 --> STEP4
    STEP4 --> STEP5
    STEP3 --> STEP5

5. Dataset Specifications & Schema

The primary operational dataset (synthetic_fraud_dataset1.csv) contains 50,000 transaction records capturing financial, behavioral, and demographic dimensions.

Attribute Dictionary

Field Name	Data Type	Description	Operational Significance
`Transaction_ID`	String (Categorical)	Unique identifier for each transaction event	Used for transactional tracing and audit logs
`User_ID`	String (Categorical)	Unique customer account identifier	Tracks multi-card and user-level velocity
`Transaction_Amount`	Float (Continuous)	Financial value of the transaction in USD	Primary monetary risk indicator
`Transaction_Type`	String (Nominal)	Channel (`ATM Withdrawal`, `Bank Transfer`, `Online`, `POS`)	Identifies channel-specific fraud vulnerability
`Date`	Datetime (String)	Timestamp of transaction initiation	Enables temporal decomposition & trend analysis
`Account_Balance`	Float (Continuous)	Liquid balance available in customer account	Basis for liquidity drain ratio calculations
`Device_Type`	String (Nominal)	Originating terminal (`Laptop`, `Mobile`, `Tablet`)	Flags device switching or botnet automation
`Location`	String (Nominal)	Geolocation (`Mumbai`, `New York`, `Sydney`, `Tokyo`)	Detects impossible travel or regional risk spikes
`Merchant_Category`	String (Nominal)	Sector (`Clothing`, `Electronics`, `Groceries`, `Restaurants`, `Travel`)	Identifies high-risk merchant categories
`Previous_Fraudulent_Activity`	Integer (Binary)	Historical indicator of prior account fraud (`0` or `1`)	High-weight prior recidivism risk factor
`Daily_Transaction_Count`	Integer (Discrete)	Number of transactions executed in past 24 hours	Measures rapid velocity burst patterns
`Card_Type`	String (Nominal)	Card network (`Amex`, `Discover`, `Mastercard`, `Visa`)	Network-specific settlement risk segmentation
`Card_Age`	Integer (Discrete)	Longevity of payment card in days	Flags newly provisioned card exploitation
`Fraud_Label`	Integer (Target)	Ground truth status (`0` = Legitimate, `1` = Fraudulent)	Binary supervised machine learning target

6. Data Cleansing & Ingestion Pipeline

The data cleaning module (src/data_cleaning.py) guarantees data sanitization and deterministic schema conformation:

Deduplication: Drops exact duplicates to prevent sample overrepresentation.
Datetime Normalization: Converts diverse datetime representations into structured ISO-compliant pandas timestamps.
Missing Value Treatment: Identifies and isolates corrupted or null records, ensuring a complete and uncorrupted dataset for modeling.
Automated Directory Provisioning: Programmatically generates processed storage folders (data/processed/) upon execution.

7. Feature Engineering & Mathematical Formulations

To maximize the discriminatory power of the Random Forest model, the raw inputs are converted into domain-specific features (src/feature_engineering.py):

1. Amount-to-Balance Liquidity Ratio

Fraudulent actors typically attempt to drain maximal capital relative to available account liquidity before card cancellation: $$\text{Amount_to_Balance_Ratio} = \frac{\text{Transaction_Amount}}{\text{Account_Balance} + 1}$$ The $+1$ denominator term represents Laplace smoothing to prevent division by zero for depleted balance accounts.

2. High Amount Anomaly Flag

Identifies transactions that exceed the empirical median transaction value: $$\text{High_Amount_Flag} = \begin{cases} 1, & \text{if } \text{Transaction_Amount} > \text{Median}(\text{Transaction_Amount}) \ 0, & \text{otherwise} \end{cases}$$

3. High Frequency Burst Flag

Flags accounts experiencing abnormal transaction counts within a single 24-hour cycle: $$\text{High_Transaction_Frequency} = \begin{cases} 1, & \text{if } \text{Daily_Transaction_Count} > \text{Median}(\text{Daily_Transaction_Count}) \ 0, & \text{otherwise} \end{cases}$$

4. Temporal Decomposition

Extracts 4 cyclical components to capture human vs. bot temporal rhythms:

$\text{Transaction_Year} = \text{Year}(\text{Date})$
$\text{Transaction_Month} = \text{Month}(\text{Date})$
$\text{Transaction_Day} = \text{Day}(\text{Date})$
$\text{Transaction_DayOfWeek} = \text{DayOfWeek}(\text{Date}) \in [0, 6]$

5. Multi-Channel Categorical One-Hot Encoding

Categorical string columns are expanded into binary vectors ($k-1$ dummy columns per category to eliminate multicollinearity):

Transaction Types: Bank Transfer, Online, POS (with ATM Withdrawal as baseline).
Device Types: Mobile, Tablet (with Laptop as baseline).
Locations: Mumbai, New York, Sydney, Tokyo.
Merchant Categories: Electronics, Groceries, Restaurants, Travel (with Clothing as baseline).
Card Networks: Discover, Mastercard, Visa (with Amex as baseline).

Result: A 29-column feature matrix saved to data/processed/feature_engineered_fraud_data.csv.

8. Exploratory Data Analysis & Risk Patterns

The automated EDA script (src/eda.py) generates 8 statistical charts rendered at 300 DPI in outputs/figures/:

fraud_distribution.png: Class imbalance breakdown (33,933 Legitimate vs. 16,067 Fraudulent transactions).
transaction_amount_by_fraud.png: Boxplot distribution demonstrating higher variance and elevated upper-quartile amounts in fraudulent activity.
transaction_type_vs_fraud.png: Channel comparison highlighting disproportionate fraud incidence in online payments and bank transfers.
device_type_vs_fraud.png: Device origin comparison showing heightened risk across mobile and tablet transactions.
merchant_category_vs_fraud.png: Sector breakdown demonstrating high anomaly concentrations in Travel and Electronics categories.
previous_fraud_activity.png: History recidivism analysis verifying that accounts with prior fraud flags have higher subsequent fraud probabilities.
daily_transaction_count.png: Daily frequency analysis illustrating the velocity burst characteristic of automated carding attacks.
account_balance_by_fraud.png: Liquidity profile comparison highlighting capital depletion anomalies.

9. Machine Learning Model Architecture

The classification core (src/train_model.py) utilizes an optimized Random Forest Classifier:

Why Random Forest?

Non-Linear Decision Boundaries: Accurately models non-linear interactions between amounts, velocity, and categorical variables.
Robustness Against Overfitting: Ensemble aggregation of 300 decorrelated decision trees reduces overall variance without increasing bias.
Robust to Outliers: Decision splits are invariant to monotonic feature scaling, remaining robust against extreme transaction values.
Inherent Interpretability: Provides Gini-importance metrics for transparency and auditability.

Hyperparameter Configuration

Hyperparameter	Configured Value	Engineering Rationale
`n_estimators`	`300`	Ensures high stability in ensemble voting and minimizes variance
`class_weight`	`"balanced"`	Automatically adjusts weights inversely proportional to class frequencies: $w_j = \frac{N}{k \cdot n_j}$
`min_samples_split`	`5`	Prevents individual trees from fitting to noisy isolated data points
`min_samples_leaf`	`2`	Guarantees terminal leaves have generalizable sample support
`random_state`	`42`	Guarantees reproducible training and benchmark results
`n_jobs`	`-1`	Utilizes all available CPU cores for fast parallel tree generation

Normalization Pipeline

Features are standardized using StandardScaler to ensure zero mean and unit variance: $$z = \frac{x - \mu}{\sigma}$$ Both the trained classifier (fraud_detection_model.pkl) and scaler (scaler.pkl) are serialized using joblib in the models/ directory.

10. Quantitative Performance Benchmarks & Validation

The model was evaluated on both an unseen 20% hold-out partition (10,000 transactions) and the complete benchmark dataset (50,000 transactions).

Validation Metrics Table

Metric	Score	Industry Standard	Evaluation Status
Accuracy	93.53%	> 90.00%	Exceeds Target
Precision (Fraud Class)	99.68%	> 95.00%	Exceptional (0.12% False Positive Rate)
Recall (Fraud Class)	80.11%	> 80.00%	High Anomaly Capture Rate
F1-Score (Fraud Class)	0.8883	> 0.8500	Robust Harmonic Balance
ROC-AUC Score	0.9787	> 0.9500	Near-Ideal Discrimination
Macro Average F1	0.9210	> 0.9000	Balanced Across Both Classes

Complete Confusion Matrix

                          Predicted Legitimate (0)    Predicted Fraudulent (1)
Actual Legitimate (0)             33,892                        41
Actual Fraudulent (1)              3,196                    12,871

Metric Interpretations:

Precision ($99.68%$): Out of $12,912$ total fraud alerts generated by the model, $12,871$ were actual fraud events. Only $41$ legitimate transactions were flagged, minimizing checkout friction for genuine customers.
Recall ($80.11%$): The model captured $12,871$ out of $16,067$ fraud events, intercepting the large majority of financial loss.
ROC-AUC ($0.9787$): Demonstrates that a randomly chosen fraudulent transaction will be assigned a higher risk probability than a legitimate one in $97.87%$ of comparisons.

11. Real-Time Inference & Automated Decision Routing

Incoming transactions are evaluated through a three-tier risk threshold policy:

flowchart TD
    INCOMMING["Incoming Transaction Request"] --> PIPELINE["Feature Normalization & Model Inference"]
    PIPELINE --> PROB{"Computed Fraud Probability (P)"}
    
    PROB -->|"P < 30%"| TIER1["Tier 1: Low Risk"]
    PROB -->|"30% <= P < 70%"| TIER2["Tier 2: Moderate Risk"]
    PROB -->|"P >= 70%"| TIER3["Tier 3: Critical Risk"]
    
    TIER1 --> ACTION1["Action: AUTO-APPROVE<br/>Latency: < 5ms"]
    TIER2 --> ACTION2["Action: CHALLENGE (2FA / Biometric OTP)<br/>Step-Up Verification"]
    TIER3 --> ACTION3["Action: IMMEDIATE DECLINE & HOLD<br/>Security Notification Dispatched"]

12. Enterprise Sky Blue Intelligence Dashboard

The Streamlit web application (dashboard/app.py) provides an interactive interface featuring an Enterprise Sky Blue Light Theme:

streamlit run dashboard/app.py

Dashboard Feature Breakdown

Overview & Landing Portal:
- High-impact hero section with system status telemetry and key KPI badges.
- 4 Animated feature cards highlighting system capabilities.
- Instant Assessment Sandbox: Live interactive sliders to test fraud probabilities without leaving the landing page.
Executive Command Center:
- Monitored volume metrics and total capital protected.
- Interactive Plotly scatter distributions, portfolio fraud ratio donuts, and payment channel breakdowns.
Real-Time Risk Simulator:
- 4 One-click scenario presets:
  - "Legitimate Everyday Purchase"
  - "Suspicious Rapid POS Burst"
  - "High-Value Overseas Transfer"
  - "ATM Cash Out Attempt"
- Dynamic Risk Gauge: Multi-zone meter displaying real-time risk scores with color-coded thresholds.
- Multi-Vector Behavioral Radar: 5-axis polar chart comparing current transactions against baseline legitimate and fraudulent behavioral profiles.
Visual Analytics & Patterns:
- Dynamic cross-filtering by channel, merchant sector, and transaction amount ranges.
- 3D Feature Interaction Space: Rotatable, zoomable 3D scatter plot (Amount vs Balance vs Velocity).
- Transaction Hierarchy Sunburst: Multi-level visual pathway (Channel -> Location -> Fraud Status).
- Correlation matrix heatmap with hover values.
Batch Forensic Auditor:
- Supports CSV batch uploads or automated sample generation.
- Fast batch inference with risk threshold filtering.
- One-click export of scored predictions as downloadable CSV.
Model Performance Forensics:
- Gini feature importance rankings from the Random Forest model.
- Interactive confusion matrix and complete classification report.

13. CLI Pipeline Orchestration (`main.py`)

The pipeline includes a centralized CLI driver with argument parsing for automated workflows:

CLI Command	Action Performed
`python main.py --step all`	Executes the complete end-to-end pipeline from data cleaning to inference
`python main.py --step clean`	Ingests raw data and writes cleaned CSV to `data/processed/`
`python main.py --step features`	Generates the 29-column feature engineered matrix
`python main.py --step eda`	Generates and saves 8 analytical figures in `outputs/figures/`
`python main.py --step train`	Trains Random Forest classifier and serializes model artifacts
`python main.py --step evaluate`	Calculates validation metrics and exports `reports/model_evaluation.txt`
`python main.py --step predict`	Tests single transaction inference and exports `outputs/prediction_result.csv`
`python main.py --skip-eda`	Runs full pipeline while bypassing plot generation for faster execution

14. Installation & Operational Setup

Prerequisites

Python 3.10 to 3.13
Git 2.30+

Setup Instructions

# 1. Clone the repository
git clone https://github.com/ut3av/ZidioFraudDetection.git
cd ZidioFraudDetection

# 2. Create and activate a virtual environment
# Windows:
python -m venv .venv
.venv\Scripts\Activate.ps1

# Linux / macOS:
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run the full machine learning pipeline
python main.py --step all

# 5. Launch the Sky Blue Streamlit Dashboard
streamlit run dashboard/app.py

15. REST API Integration Schema

To deploy FraudShield AI behind a FastAPI or Flask microservice endpoint:

HTTP Request Specification

Method: POST
Endpoint: /api/v1/fraud/assess
Headers: Content-Type: application/json

Request Payload

{
  "Transaction_Amount": 749.50,
  "Account_Balance": 820.00,
  "Previous_Fraudulent_Activity": 1,
  "Daily_Transaction_Count": 14,
  "Card_Age": 45,
  "Transaction_Type": "Bank Transfer",
  "Device_Type": "Laptop",
  "Location": "Tokyo",
  "Merchant_Category": "Travel",
  "Card_Type": "Discover"
}

Response Payload

{
  "transaction_id": "TXN_EVAL_98124",
  "prediction": "FRAUDULENT",
  "fraud_probability_percentage": 92.40,
  "risk_tier": "CRITICAL",
  "decision": "DECLINE_AND_HOLD",
  "latency_ms": 4.1,
  "timestamp": "2026-09-09T16:05:00Z"
}

16. Production Deployment & Containerization

Docker Deployment

Create a Dockerfile in the project root:

FROM python:3.13-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Run training to serialize local model artifacts
RUN python main.py --step all

EXPOSE 8501

CMD ["streamlit", "run", "dashboard/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

Build and Run Container

docker build -t fraudshield-ai:latest .
docker run -p 8501:8501 fraudshield-ai:latest

17. Security, Governance & Compliance

PCI-DSS Compliance Readiness: Raw card numbers and sensitive PAN data are never stored; the model uses tokenized card age and categorical types only.
Model Explainability & Auditability: Every automated classification can be decomposed into Gini feature importance contributions and radar risk vectors for regulatory compliance.
Non-Invasive Architecture: Model binaries are stored locally and excluded from git tracking via .gitignore to prevent repository bloat and proprietary weight exposure.

18. Project Directory Hierarchy

ZidioFraudDetection/
|-- .streamlit/
|   `-- config.toml                     # Streamlit Light Sky Blue theme configuration
|-- dashboard/
|   `-- app.py                          # Multi-page Sky Blue intelligence dashboard
|-- data/
|   |-- raw/
|   |   `-- synthetic_fraud_dataset1.csv # Raw transactional dataset (50,000 records)
|   `-- processed/
|       |-- cleaned_fraud_data.csv       # Cleaned transactional records
|       `-- feature_engineered_fraud_data.csv # 29-column feature matrix
|-- models/
|   |-- fraud_detection_model.pkl       # Serialized Random Forest classifier
|   `-- scaler.pkl                      # Serialized StandardScaler
|-- outputs/
|   |-- figures/                        # 8 High-resolution (300 DPI) EDA figures + Hero banner
|   |   |-- hero_banner.jpg
|   |   |-- account_balance_by_fraud.png
|   |   |-- daily_transaction_count.png
|   |   |-- device_type_vs_fraud.png
|   |   |-- fraud_distribution.png
|   |   |-- merchant_category_vs_fraud.png
|   |   |-- previous_fraud_activity.png
|   |   |-- transaction_amount_by_fraud.png
|   |   `-- transaction_type_vs_fraud.png
|   `-- prediction_result.csv           # Sample inference output CSV
|-- reports/
|   `-- model_evaluation.txt            # Benchmark evaluation report
|-- src/
|   |-- __init__.py
|   |-- data_cleaning.py                # Ingestion and data cleaning logic
|   |-- data_loading.py                 # Dataset inspection utilities
|   |-- eda.py                          # Statistical EDA plot generator
|   |-- evaluate_model.py               # Quantitative validation routines
|   |-- feature_engineering.py          # Feature extraction and encoding pipeline
|   |-- fraud_prediction.py             # Standalone programmatic inference engine
|   `-- train_model.py                  # Model training and artifact serialization
|-- .gitignore                          # Git exclusion configuration
|-- main.py                             # Unified CLI pipeline orchestrator
|-- README.md                           # Master project documentation
`-- requirements.txt                    # System dependencies

19. Troubleshooting & Frequently Asked Questions

Q1: Why are `.pkl` model files excluded from Git?

The Random Forest model file is ~321 MB. GitHub enforces a strict 100 MB per-file limit. The pipeline can regenerate model artifacts locally at any time in seconds by executing:

python main.py --step train

Q2: How can I change the classification decision threshold?

In dashboard/app.py and src/fraud_prediction.py, the default classification threshold is 0.50 ($50%$). You can adjust the sensitivity threshold (e.g., to 0.30 for aggressive risk interception) via the interactive slider in the Batch Forensic Auditor.

Q3: How do I verify all dependencies are installed properly?

Run the following validation command:

python -c "import pandas, sklearn, joblib, matplotlib, seaborn, plotly, streamlit; print('All dependencies verified successfully')"

License & Attribution

Developed under Zidio Development as an enterprise-grade financial fraud detection reference architecture.

Name		Name	Last commit message	Last commit date
.streamlit		.streamlit
dashboard		dashboard
data		data
outputs		outputs
reports		reports
src		src
.gitignore		.gitignore
README.md		README.md
main.py		main.py
pyrightconfig.json		pyrightconfig.json
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation