Skip to content

Latest commit

 

History

History
323 lines (250 loc) · 8.69 KB

README.md

File metadata and controls

323 lines (250 loc) · 8.69 KB

🔍 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.

Python FastAPI XGBoost Docker License

📋 Table of Contents

🎯 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
  1. Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies
pip install -r requirements.txt
  1. Run the application
uvicorn app:app --reload
  1. Open the web interface

🎮 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:

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

🙏 Acknowledgments

📞 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