docs/architecture.md

# MuleGuard — Architecture & Data Flow

## System architecture

![Architecture](architecture.png)

**Ingestion** — In production, MuleGuard consumes financial transactions, Fraud/Transaction Monitoring System (FMS/TMS) alerts, government cyber-fraud tickets (I4C / NCRP-1930), and cross-channel bank data. For the hackathon, these are represented by the provided feature dataset and a feed simulator.

**Feature pipeline** — A single fitted `FeatureBuilder` cleans the data (parses the open-date to account age, ordinally encodes the activity-recency bucket, one-hot-encodes account type / occupation / segment / gender), median-imputes numerics, and **fuses an Isolation Forest anomaly score** that flags novel behavior beyond known patterns. It then selects a stable ~103-feature subset via cross-validated importance voting while retaining the bank-flagged domain-prior features.

**ML model** — A LightGBM gradient-boosted classifier with class-imbalance weighting, wrapped in probability calibration. SHAP provides per-account reason codes.

**Scoring API** — FastAPI service that turns a raw account record into a `risk score (0–100)`, `tier`, `decision`, and `reason codes`.

**Feed simulator** — Streams held-out accounts and synthetic regulatory tickets into the scorer, mimicking a live cross-channel feed and producing the alert queue.

**Analyst console** — Streamlit app: live alert queue, account drill-down with SHAP explanations, and model-performance panels.

## Modeling pipeline

![Pipeline](pipeline_flow.png)

## Train/serve parity

Training, evaluation, the API, the simulator, and the dashboard all load the **same** persisted artifacts (`feature_pipeline.pkl`, `model.pkl`, `threshold.json`, `feature_list.json`, `shap_explainer`). There is no divergence between how the model is trained and how it scores in production.

## Engineering rigor — leakage defense

Two features were detected and **excluded as leakage** before modeling:

| Feature | Issue | Single-feature AUC |
|---|---|---|
| `F3912` | Binary "fraud-flagged" indicator, ~identical to the label (1 for 79/81 mules) | 0.987 |
| `F2230` | Observation month — all legit accounts in Oct25, all mules in Sep/Nov/Dec25 (temporal sampling artifact) | 1.000 |

Including either would have produced a fake ~100% score. Their removal — and the large gap between LightGBM (CV PR-AUC ≈ 0.88) and a logistic baseline (≈ 0.39) — confirms the model learns genuine non-linear behavioral signal, not label shortcuts.