docs/architecture.md

MuleGuard — Architecture & Data Flow

System architecture

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

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.