README.md

🛡️ Sentinel: Real-Time Fraud Detection System

Sentinel is an end-to-end, machine-learning-powered fraud detection system that analyzes financial transactions within milliseconds.

Built using modern MLOps principles, it unifies data processing, model training, API services, database logging, and monitoring dashboards under a single architecture.

---

🏗️ System Architecture

graph LR
    User[Client / Simulator] -->|POST /predict| API[FastAPI Service]
    API -->|1. Preprocessing| Preproc[Feature Engineering]
    Preproc -->|2. Inference| Model[XGBoost Pipeline]
    Model -->|3. Prediction| API
    API -->|4. Logging| DB[(SQLite / Postgres)]
    API -->|Response| User
    User -->|Monitor| Dashboard[Streamlit App]

Loading

🚀 Features

• Advanced Feature Engineering: Time-based and geo-mismatch feature extraction.
• Imbalance Handling: Uses scale_pos_weight for highly imbalanced datasets.
• Robust API: Async FastAPI architecture with Pydantic v2 validation.
• Audit Trail: Every prediction is logged into the database.
• Dockerized: Entire system can be launched with a single command.

---

🛠️ Installation

1. Using Docker (Recommended)

make up
# Stop the system
make down

API: http://localhost:8000/docs Dashboard: http://localhost:8501

2. Manual Installation

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run training
python src/ml_core/train.py

# Start the API
python src/main.py

# Start the dashboard
streamlit run dashboard.py

---

🧪 Testing

Automated tests ensure system reliability.

make test
# or
pytest -v

---

📂 Project Structure

sentinel-fraud-detection-system/
├── src/
│   ├── ml_core/       # Model training & artifacts
│   ├── routers/       # API endpoints
│   ├── services/      # Business logic (Inference & Preprocessing)
│   ├── db/            # Database connections
│   └── models/        # SQLAlchemy schemas
├── tests/             # Integration tests
├── dashboard.py       # Streamlit monitoring dashboard
├── Dockerfile         # Container definition
└── Makefile           # Command automation

Developed by Efekan Salman — 2025