How rajaramanpa/fraud-prevention-detection-system works
Purpose and entry points
PayGuard is a payment-fraud trust layer for simulated bank payments. It scores a payment, returns Approved/Risky/Blocked, persists outcomes, and exposes analyst and customer-facing clients.
• API/service and static payment simulator: api/main.py, iobpay/index.html
• Analyst console: dashboard/app.py
• Model-training entry points: data/generate_synthetic.py, models/train_pipeline.py
API orchestration boundary
api/main.py is the central runtime boundary. It loads serialized ML artifacts, accepts payment payloads through /score and batch scoring, composes model and stateful signals into the final transaction trust/risk score, and exposes history, reputation, trust, governance, and health endpoints.
It also serves the single-file React simulator under /pay/; dashboard and simulator are HTTP clients rather than direct callers of model or database code.
Paths: api/main.py, iobpay/index.html, dashboard/app.py.
Fraud scoring pipeline
A payment is transformed into the trained feature schema, scaled, and evaluated by two complementary models:
• LightGBM supplies supervised fraud probability.
• Isolation Forest supplies novelty/anomaly scoring.
• SHAP produces per-payment feature explanations.
Persisted artifacts make inference independent of training at runtime.
Paths: models/lgb_model.pkl, models/iso_model.pkl, models/scaler.pkl, models/feature_cols.pkl, models/shap_explainer.pkl.
Risk decision composition
The API blends transaction-model risk with device, authentication/session, customer-history, beneficiary reputation, and shared-memory signals into a 0–100 risk score. Thresholds map it to Approved, Risky (step-up verification), or Blocked. Reputation is an escalation-only override: known bad entities can force Risky/Blocked. A blocked payment feeds receiver/device evidence back into memory for later requests.
The customer trust score is deliberately separate from transaction risk: it is durable, per-customer history that becomes one signal in later decisions.
Paths: models/trust_engine.py, models/reputation.py, api/main.py.
Stateful intelligence and persistence
SQLite is the durable boundary for transactions, customer trust/history, and the receiver/device reputation ledger. On startup, state is restored; after scoring or fraud reporting, updates are written back. This supports the dashboard’s historical investigations and the fraud-memory feedback loop across API restarts.
The “blockchain” terminology is only a simulation: no distributed ledger runtime exists; the shared-memory ledger is SQLite-backed.
Paths: models/db.py, models/reputation.py, api/main.py.
User-facing flows
The IOB Pay simulator creates synthetic payment requests, including safe/suspicious/compromised profiles, and renders the API decision. Its React dependency is CDN-loaded, with no frontend build system.
The Streamlit dashboard reads API endpoints to display recent activity, outcome analytics, selected-transaction explanations, risk-breakdown details, compliance reports, and ledger state. It does not originate payments.
Paths: iobpay/index.html, dashboard/app.py, api/main.py.
Training and operational runtime
Training starts by enriching fraud data with behavioral/device/session features, then trains and serializes classifier, anomaly model, scaler, feature metadata, thresholds, parameters, importances, and SHAP explainer. The repository already includes the resulting .pkl artifacts for serving.
Material runtimes are Python/FastAPI with Uvicorn, Streamlit, SQLite via built-in sqlite3, pandas/NumPy, LightGBM, scikit-learn Isolation Forest, SHAP, and Plotly. No external database, payment rail, blockchain network, or cloud service is required.
Paths: data/generate_synthetic.py, models/train_pipeline.py, requirements.txt.
Main entry points: main.py Risk decision composer · db.py SQLite state store · reputation.py Reputation ledger · train_pipeline.py Model training pipeline
Components 12
User clients
- IOB Pay simulator · Creates simulated payment profiles and displays decisions.
iobpay/index.html - Analyst dashboard · Investigates history, explanations, reports, and ledger state.
dashboard/app.py
Serving runtime
- PayGuard API · Central HTTP runtime for scoring, history, reputation, trust, and governance.
api/main.py - Risk decision composer · Blends model and stateful signals into 0–100 risk and outcome.
api/main.py - Serialized ML artifacts · LightGBM, Isolation Forest, scaler, feature schema, and SHAP explainer.
- SQLite state store · Durable transactions, trust history, and reputation ledger.
models/db.py
Risk intelligence
- Customer trust engine · Maintains durable customer trust separately from transaction risk.
models/trust_engine.py - Reputation ledger · Tracks receiver and device evidence; bad entities can escalate outcomes.
models/reputation.py - Fraud-memory feedback · Blocked payments add receiver and device evidence for future scoring.
api/main.py
Training pipeline
- Synthetic data generation · Enriches fraud data with behavioral, device, and session features.
data/generate_synthetic.py - Model training pipeline · Trains models and serializes inference metadata and explainers.
models/train_pipeline.py - Python runtime dependencies · FastAPI, Streamlit, ML libraries, SHAP, Plotly, and SQLite support.
requirements.txt
Connections 15
- IOB Pay simulator → PayGuard API: HTTP payment scoring
- Analyst dashboard → PayGuard API: HTTP investigations
- PayGuard API → Risk decision composer: score requests
- Serialized ML artifacts → Risk decision composer: model probability, anomaly, SHAP
- Customer trust engine → Risk decision composer: customer-history signal
- Reputation ledger → Risk decision composer: entity escalation
- Risk decision composer → SQLite state store: persist outcome and history
- SQLite state store → Customer trust engine: restore and update trust
- SQLite state store → Reputation ledger: restore ledger evidence
- Risk decision composer → Fraud-memory feedback: blocked outcome
- Fraud-memory feedback → Reputation ledger: receiver/device evidence
- Synthetic data generation → Model training pipeline: enriched training data
- Model training pipeline → Serialized ML artifacts: serialize serving artifacts
- Python runtime dependencies → PayGuard API: serves runtime
- Python runtime dependencies → Model training pipeline: trains models