executor1389/RealTimeCreditCardFraudDetectionApi
0
1---2title: FraudShield AI3emoji: 🛡️4colorFrom: indigo5colorTo: purple6sdk: docker7pinned: false8---9 10# FraudShield AI: Real-Time Credit Card Fraud Detection11 12## Website: https://huggingface.co/spaces/executor1389/RealTimeCreditCardFraudDetectionApi13 1415 16[](https://github.com/dpetrovic89/RealTimeCreditCardFraudDetectionApi/actions)17 18FraudShield AI is a production-ready MLOps ecosystem designed to detect fraudulent credit card transactions in real-time. Built with a 100% free-tier stack, this project demonstrates senior-level engineering across the entire data-to-deployment lifecycle.19 20## 🏗️ Architecture Stack21 22FraudShield AI implements a layered architecture from data ingestion to real-time serving. See the [**System Architecture Guide**](architecture.md) for full details and diagrams.23 24- **Model**: LightGBM (89% Recall on real Kaggle data)25- **Serving**: FastAPI + Docker (serving on port 7860/8000)26- **Frontend**: Premium Glassmorphic UI 27- **Monitoring**: Evidently AI + Prometheus28- **CI/CD**: GitHub Actions (Auto-Sync to Hugging Face)29 30---31 32## 📊 Data Privacy & Source33 34- **Real Data**: The project is designed for the [Kaggle Credit Card Fraud Detection](https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud) dataset. Due to its 150MB size, it is git-ignored and stored locally in `data/creditcard.csv`.35- **Mock Data**: For CI/CD and testing on the cloud, a `scripts/generate_data.py` utility creates a synthetic dataset that mimics the real distribution without exposing sensitive information.36- **Model Storage**: The "wisdom" of the real data is compressed into the 7KB [src/model.txt](src/model.txt) used by the API.37 38---39 40## 🚀 Step-by-Step Deployment Guide41 42Follow these steps to get the full stack running on your machine.43 44### 1. Prerequisites45Ensure you have the following installed:46- Python 3.10+47- Docker Desktop48- Minikube (for Kubernetes deployment)49- Git50 51### 2. Local Setup52```bash53# Clone the repository54git clone https://github.com/dpetrovic89/RealTimeCreditCardFraudDetectionApi.git55cd RealTimeCreditCardFraudDetectionApi56 57# Install dependencies58pip install -r requirements.txt59```60 61### 3. Run with Python (Development)62```bash63# Start the FastAPI server64uvicorn src.app:app --host 0.0.0.0 --port 8001 --reload65```66Access the frontend by opening `frontend/index.html` in your browser.67 68### 4. Run with Docker69```bash70# Build the image71docker build -t fraud-detection-api .72 73# Run the container74docker run -p 8001:8000 fraud-detection-api75```76 77### 5. Deploy to Kubernetes (Minikube)78```bash79# Start Minikube80minikube start81 82# Apply manifests83kubectl apply -f k8s/deployment.yaml84 85# Expose the service86minikube service fraud-detection-service87```88 89### 6. Deploy to Hugging Face Spaces (ML Optimized & Free)901. Create a "New Space" on [Hugging Face](https://huggingface.co/spaces).912. Select **Docker** as the SDK.923. Push your GitHub repository (or upload files).934. Hugging Face will build the `Dockerfile` and host your app on port 7860!94 95### 7. Deploy to Vercel (Fastest & Free)96This app is optimized for Vercel Serverless Functions.971. Install Vercel CLI: `npm i -g vercel`982. Run `vercel` in the root directory.993. Your frontend will be at `https://your-project.vercel.app`.100 101### 8. Activate CI/CD102To enable automated builds and tests:1031. Go to your GitHub Repo > **Settings** > **Secrets and variables** > **Actions**.1042. Add the following secrets:105 - `DOCKERHUB_USERNAME`: Your Docker Hub username.106 - `DOCKERHUB_TOKEN`: Your Docker Hub Access Token.1073. Every push to `main` will now trigger a build and push to Docker Hub!108 109---110 111## 📊 Monitoring & Data Quality112- **Validation**: Run `python scripts/data_validation.py` to check data health via Great Expectations.113- **Drift**: Run `python src/monitor.py` to generate an Evidently AI report (`monitoring/drift_report.html`).114- **Metrics**: Prometheus scrapes API performance data on port 8001.115 116## 📄 License117This project uses the Kaggle Credit Card Fraud Detection dataset. Distributed under the MIT License.118