Victor-Kipruto-Rop/mpesa_safaricom-fraud_anomaly_detection

Real-time fraud detection engine for M-Pesa mobile money — Kafka/Flink streaming, ML-based risk scoring, and explainable multi-signal checks (velocity, SIM swap correlation, mule networks) feeding an interaction-aware decision engine, with a full production pipeline from ingestion through dbt analytics. # M-Pesa Fraud Anomaly Detection System A production-grade, real-time fraud detection engine for M-Pesa mobile money transactions. It combines rule-based checks with machine learning scoring, multi-domain orchestration, circuit breaker resilience, and full audit logging. This is the standalone fraud detection component of the broader M-Pesa streaming platform. It contains the scoring engine, rule checks, ML artifacts, dashboards, deployment assets, and operational docs for local testing, staging validation, and deployment. Main entry points: the API service, scoring engine, dashboard app, and Docker Compose setup. Validate changes by running the unit/integration test suite, exercising the API locally, and confirming staging pipeline health. ## Quick Start **Prerequisites:** Python 3.10+, PostgreSQL 13+, Redis (optional — feature caching) **Install:** ```bash cd mpesa_safaricom/fraud_anomaly_detection pip install -r requirements.txt ``` **Run tests:** ```bash PYTHONPATH=../real_time_transaction_streaming:..:. \ python -m pytest tests/ --cov=. --cov-report=html -v ``` Current coverage: **48%** (1,991 statements, 30 passing tests). **Train the ML model:** ```bash python ml/train_model.py \ --data ml/synthetic_transactions.parquet \ --output-dir models/run_$(date +%Y-%m-%d_%H) \ --imbalance-method balanced \ --sample-size 100 ``` Produces a calibrated classifier, a model card, and optional SHAP explanations. ## Architecture The engine scores each transaction in three layers: 1. **Transaction-level checks** — velocity, SIM swap, night-hour activity, mule accounts 2. **ML scoring** — HistGradientBoosting with calibrated probabilities 3. **Decision aggregation** — weighted scoring, circuit breaker, audit logging ``` Incoming Transaction │ ▼ Schema Validation ──► DLQ (invalid) │ ▼ Velocity Check · SIM Swap Correlator · Night Hour Flagger Mule Account Detector · ML Fraud Scorer │ ▼ Aggregator ──► Risk Score (0–100) │ ▼ Circuit Breaker │ ▼ Decision + Audit Log ``` …