🔍 Fraud Detection System

A full-stack machine learning application for detecting fraudulent credit card transactions using XGBoost. Features a FastAPI backend, interactive web interface, and Docker deployment.

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Project Structure
• Installation
• Usage
• API Documentation
• Docker Deployment
• Model Details
• Contributing
• License

🎯 Overview

This fraud detection system uses machine learning to identify potentially fraudulent credit card transactions in real-time. The system analyzes transaction patterns including amount, location, cardholder demographics, and temporal features to predict fraud with high accuracy.

Key Highlights

• Real-time predictions via REST API
• Interactive web interface for easy testing
• XGBoost classifier trained on historical transaction data
• Feature engineering including time-based and behavioral features
• Containerized deployment with Docker
• Transparent predictions with confidence scores and feature visibility

✨ Features

• 🚀 Fast API Backend - High-performance REST API built with FastAPI
• 🎨 Modern Web UI - Clean, responsive interface for transaction testing
• 🤖 ML-Powered Detection - XGBoost model for accurate fraud prediction
• 📊 Feature Transparency - View generated features used in predictions
• 🐳 Docker Ready - Easy deployment with Docker and Docker Compose
• 📈 Confidence Scoring - Get probability scores for each prediction
• ⚡ Real-time Processing - Instant fraud detection results

🛠 Tech Stack

Backend

• FastAPI - Modern Python web framework
• XGBoost - Gradient boosting machine learning library
• Pandas - Data manipulation and analysis
• Scikit-learn - Machine learning preprocessing
• Joblib - Model serialization

Frontend

• HTML5/CSS3 - Responsive web interface
• JavaScript (Vanilla) - Interactive client-side functionality

DevOps

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• Uvicorn - ASGI server

📁 Project Structure

fraud-detection/
├── app.py                      # FastAPI application
├── index.html                  # Web interface
├── Dockerfile                  # Docker configuration
├── docker-compose.yml          # Docker Compose configuration
├── requirements.txt            # Python dependencies
├── .dockerignore              # Docker ignore file
├── models/                     # Trained ML models and preprocessors
│   ├── xgbmodel.jb
│   ├── preprocessor_pipeline.jb
│   └── target_encoder.jb
├── data/                       # test Dataset
│   └── fraudTest.csv
└── README.md                   # Information about the project

🚀 Installation

Prerequisites

• Python 3.9+
• Docker (optional, for containerized deployment)
• pip (Python package manager)

Local Setup

1. Clone the repository

git clone https://github.com/aadedolapo/Fraud-detection.git
cd Fraud-detection

2. Create a virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Run the application

uvicorn app:app --reload

5. Open the web interface

• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Open index.html in your browser for the UI

🎮 Usage

Web Interface

1. Open index.html in your web browser
2. Fill in the transaction details:
   • Category: Transaction category (e.g., gas_transport, grocery_pos)
   • Amount: Transaction amount in USD
   • Gender: Cardholder gender (M/F)
   • Job: Cardholder occupation
   • Distance: Distance from home (km)
   • Cardholder Age: Age of the cardholder
   • Day of Week: Transaction day
3. Click "Analyze Transaction"
4. View the prediction result (FRAUD/LEGIT) with confidence score
5. Click "Show Generated Features" to see additional features used in prediction

API Endpoint

POST /predict

Request body:

{
  "category": "gas_transport",
  "amt": 50.0,
  "gender": "M",
  "job": "Engineer",
  "distance": 5.0,
  "cardholder_age": 30,
  "dayofweek": "Monday"
}

Response:

{
  "prediction": 0,
  "label": "LEGIT",
  "probability": 0.9234,
  "generated_features": {
    "city_pop": 1250,
    "trans_hour": 14,
    "night_trans": 0,
    "trans_30min": 3,
    "amt_30min": 4500,
    "time_since_last_trans": 450,
    "amt_vs_avg_user_amt": 12.5
  }
}

Using cURL

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "gas_transport",
    "amt": 50.0,
    "gender": "M",
    "job": "Engineer",
    "distance": 5.0,
    "cardholder_age": 30,
    "dayofweek": "Monday"
  }'

📚 API Documentation

FastAPI provides interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Available Endpoints

Endpoint	Method	Description
/	GET	Health check
/jobs	GET	Get available job titles
/predict	POST	Predict transaction fraud status

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Build and start the container
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

Using Docker Commands

# Build the image
docker build -t fraud-detection-api .

# Run the container
docker run -p 8000:8000 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  --name fraud-api \
  fraud-detection-api

# Stop the container
docker stop fraud-api
docker rm fraud-api

Docker Configuration

The application is configured with:

• Resource Limits: 2 CPU cores, 2GB RAM (adjustable in docker-compose.yml)
• Health Checks: Automatic monitoring of container health
• Volume Mounts: Models and data directories mounted for easy updates
• Restart Policy: Automatically restarts on failure

🧠 Model Details

Algorithm

XGBoost (eXtreme Gradient Boosting)

• Ensemble learning method using gradient boosting
• Highly effective for imbalanced classification problems
• Fast training and prediction speeds

Features Used

User-Provided Features:

• Transaction category
• Transaction amount
• Cardholder gender
• Cardholder job
• Distance from home
• Cardholder age
• Day of week

Generated Features:

• City population
• Transaction hour
• Night transaction flag (0-6 AM)
• Transactions in last 30 minutes
• Amount spent in last 30 minutes
• Time since last transaction
• Amount vs average user amount ratio

Model Performance

• Training Data: Historical credit card transactions
• Preprocessing: StandardScaler, Target Encoding
• Class Imbalance Handling: Built into XGBoost

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide for Python code
• Add tests for new features
• Update documentation as needed
• Ensure Docker builds successfully

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Adedolapo

• GitHub: @aadedolapo

🙏 Acknowledgments

• Dataset: Credit card fraud detection dataset.
• XGBoost: The gradient boosting library
• FastAPI: Modern Python web framework
• Community contributors

📞 Support

For support, please open an issue in the GitHub repository or contact the maintainer.

---

⚠️ Disclaimer: This system is for educational and demonstration purposes. For production use in financial systems, additional security measures, compliance checks, and rigorous testing are required.

Made with ❤️ by Adedolapo