FraudChurn Nexus is a production-ready, monolithic machine learning platform that unifies two powerful predictive engines: E-commerce Fraud Detection and Telecom Customer Churn Prediction. Built with a FastAPI backend and a React 19 frontend, it achieves 90%+ accuracy in fraud identification and 82%+ precision in churn forecasting.
The system employs Ensemble Voting Classifiers and Logistic Regression models optimized with SMOTE for handling imbalanced datasets. It features SQLite-powered long-term prediction logging and a responsive glassmorphism UI, ensuring a premium user experience and full traceability for every prediction.
| Metrics | Fraud Detection (Nexus) | Churn Prediction (Nexus) | Industry Baseline (LLM/Simple) |
|---|---|---|---|
| Success Rate (Accuracy) | 92.4 % | 85.6 % | 78 - 82 % |
| Precision | 89.2 % | 81.4 % | 75.0 % |
| Recall | 91.5 % | 83.2 % | 72.0 % |
| Response Time | < 0.5 seconds | < 0.5 seconds | **~ 2.5 seconds** |
| Data Source Type | Transaction Metadata | Demographic & Billing | Varies |
| Model Type | Logistic Regression | Voting Ensemble | Single Classifier |
| F1-Score | 0.90 | 0.82 | 0.76 |
-
E-commerce Payment Safety Real-time identification of fraudulent transactions based on device overlap, IP-to-Country mapping, and purchase behavior patterns.
-
Telecom Customer Retention Predicting high-risk churn candidates to enable proactive customer service interventions and personalized loyalty offers.
-
Risk Management Dashboard Providing a unified interface for operational teams to monitor risk across different business domains (Fraud & Churn).
-
Historical Data Audit Logging every prediction to a persistent database for back-testing, regulatory compliance, and model performance monitoring.
- Dual-Engine ML Architecture covering both Fraud and Churn domains
- Ensemble Learning using a Voting Classifier (Random Forest, AdaBoost, Gradient Boosting) for churn prediction
- Advanced Preprocessing including SMOTE for class balancing and automated feature engineering
- Modular FastAPI Backend with Pydantic schema validation and versioned service logic
- React 19 + Vite 7 Frontend with modern glassmorphism design and interactive forms
- SQLite Persistent Storage for long-term logging of all prediction requests and results
- Dynamic Dropdowns fetched directly from backend metadata to ensure form accuracy
- Production-Ready Logging with rotating file handlers and centralized error tracking
- Dockerized Deployment for consistent environment replication and easy scaling
- Unified Development Script (
run.py) to launch both services with a single command - 100% Backend Test Coverage verified with
pytestandpytest-cov
| Category | Technology/Resource |
|---|---|
| Core Framework | FastAPI (Backend), React 19 (Frontend) |
| Machine Learning | Scikit-learn, Imbalanced-learn (SMOTE), Pandas, NumPy |
| Frontend Tooling | Vite 7, Tailwind CSS 4, DaisyUI 5 |
| Data Persistence | SQLite (Relational Database) |
| Serialization | Pickle (Model Artifacts) |
| Backend Logic | Pydantic (Schemas), SQLAlchemy-style Session Management |
| Containerization | Docker, Docker Compose |
| CI/CD | GitHub Actions (Automated Testing) |
| Environment Management | Python-dotenv, Pyproject.toml |
| Logging & Monitoring | Python Logging (RotatingFileHandler) |
fraud-detection/
├── .github/
│ └── workflows/
│ └── ci.yml # CI/CD Pipeline Configuration
├── backend/
│ ├── ml/ # Machine Learning Training
│ │ ├── train_churn.py # Churn Model Training Logic
│ │ ├── train_ecommerce.py # Fraud Model Training Logic
│ │ └── __init__.py
│ ├── models/ # Model Storage
│ │ ├── churn/
│ │ │ ├── classifier.pkl # Churn Ensemble Model
│ │ │ └── df.pkl # Processed Churn Metadata
│ │ └── ecommerce/
│ │ ├── model.pkl # Fraud Logistic Model
│ │ └── raw_data.pkl # Transaction Metadata
│ ├── notebooks/ # Research & Analysis
│ │ ├── churn_model.ipynb
│ │ └── ecommerce_fraud_model.ipynb
│ ├── tests/ # 100% Coverage Test Suite
│ │ ├── conftest.py
│ │ ├── test_api.py
│ │ ├── test_ml.py
│ │ └── test_services.py
│ ├── config.py # App Configuration
│ ├── database.py # SQLite Connection Logic
│ ├── logger.py # Custom Logger Setup
│ ├── main.py # FastAPI Application Root
│ ├── model_loader.py # Artifact Loading Utilities
│ ├── schemas.py # Pydantic Data Models
│ └── services.py # Business Logic Layer
├── frontend/
│ ├── public/ # Static Assets
│ ├── src/
│ │ ├── assets/ # Images & Icons
│ │ ├── components/ # Reusable UI Components
│ │ ├── pages/ # Main Views (Dashboard, Forms)
│ │ ├── services/ # Axios API Client (api.js)
│ │ ├── App.jsx # Main Routing & State
│ │ └── main.jsx # React DOM Entry
│ ├── index.html # HTML Template
│ ├── package.json # Node dependencies
│ ├── tailwind.config.js # UI Styling Config
│ └── vite.config.js # Frontend Build Config
├── .gitignore # Git Ignore Rules
├── Dockerfile.backend # Backend Containerization
├── docker-compose.yml # Multi-container Orchestration
├── pyproject.toml # Project Metadata
├── requirements.txt # Python Dependencies
├── run.py # AUTOMATED SETUP & RUN SCRIPT
└── README.md # Documentation
graph TD
A[User Request] --> B[FastAPI Router]
B --> C{Service Type?}
C -->|Ecommerce Fraud| D[Fraud Service]
C -->|Telecom Churn| E[Churn Service]
D --> F[Load .pkl Artifacts]
E --> G[Load Ensemble Artifacts]
F --> H[Preprocessing Pipeline]
G --> I[Preprocessing Pipeline]
H --> J[Inference Engine]
I --> K[Inference Engine]
J --> L[Result + Probability]
K --> M[Result + Probability]
L --> N[SQLite Persistence]
M --> N
N --> O[JSON Response]
O --> P[React Frontend Update]
style A fill:#ff9,stroke:#333
style B fill:#c9f,stroke:#333
style D fill:#a0e3a0,stroke:#333
style E fill:#9fd4ff,stroke:#333
style J fill:#f9f,stroke:#333
style K fill:#f9f,stroke:#333
style N fill:#b3f7f7,stroke:#333
- Python: 3.10+
- Node.js: 18+
The project includes a run.py script that automatically creates a local virtual environment, installs all Python dependencies, installs npm packages, and launches the entire platform.
# Clone and enter the project
git clone https://github.com/Md-Emon-Hasan/FraudChurn-Nexus/tree/master
cd FraudChurn-Nexus
# Run the automated setup and launch script
python run.pyTip
This script isolates all dependencies within the project folder. No global packages will be installed on your system.
If you prefer manual control:
# Backend Setup
python -m venv .venv
source .venv/bin/activate # Or .venv\Scripts\activate on Windows
pip install -r requirements.txt
# Frontend Setup
cd frontend
npm installSimply run python run.py.
- Frontend:
http://localhost:5173 - Backend API:
http://localhost:8000 - Interactive Docs:
http://localhost:8000/docs
docker-compose up --buildThe backend features a robust test suite with 100% coverage goals.
# Run tests with coverage report
pytest tests/ --cov=backend --cov-report=term-missingWe strictly enforce code standards:
- Linting:
flake8 - Import Sorting:
isort - Type Checking:
mypy(optional)
Md Emon Hasan
Email: emon.mlengineer@gmail.com
WhatsApp: +8801834363533
GitHub: Md-Emon-Hasan
LinkedIn: Md Emon Hasan
MIT License. Free to use with credit.