# rajaramanpa/fraud-prevention-detection-system architecture

> Architecture diagram of the GitHub repository rajaramanpa/fraud-prevention-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajaramanpa/fraud-prevention-detection-system
- Repository: https://github.com/rajaramanpa/fraud-prevention-detection-system

## Overview

#### 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: [`api/main.py`](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py) (Risk decision composer), [`models/db.py`](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/db.py) (SQLite state store), [`models/reputation.py`](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/reputation.py) (Reputation ledger), [`models/train_pipeline.py`](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/train_pipeline.py) (Model training pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_simulator["IOB Pay simulator<br/>Static React client<br/>[index.html]"]
  node_dashboard["Analyst dashboard<br/>Streamlit client<br/>[app.py]"]
end

subgraph group_serving["Serving runtime"]
  node_api{{"PayGuard API<br/>FastAPI service<br/>[main.py]"}}
  node_decision["Risk decision composer<br/>Decision layer<br/>[main.py]"]
  node_model_artifacts["Serialized ML artifacts<br/>Inference artifacts"]
  node_sqlite[("SQLite state store<br/>SQLite database<br/>[db.py]")]
end

subgraph group_intelligence["Risk intelligence"]
  node_trust["Customer trust engine<br/>History signal<br/>[trust_engine.py]"]
  node_reputation["Reputation ledger<br/>Escalation signal<br/>[reputation.py]"]
  node_feedback["Fraud-memory feedback<br/>State update<br/>[main.py]"]
end

subgraph group_training["Training pipeline"]
  node_synthetic_data["Synthetic data generation<br/>Data preparation"]
  node_training_pipeline["Model training pipeline<br/>ML training<br/>[train_pipeline.py]"]
  node_runtime_dependencies["Python runtime dependencies<br/>[requirements.txt]"]
end

node_simulator -->|"HTTP payment scoring"| node_api
node_dashboard -->|"HTTP investigations"| node_api
node_api -->|"score requests"| node_decision
node_model_artifacts -->|"model probability, anomaly, SHAP"| node_decision
node_trust -->|"customer-history signal"| node_decision
node_reputation -->|"entity escalation"| node_decision
node_decision -->|"persist outcome and history"| node_sqlite
node_sqlite -->|"restore and update trust"| node_trust
node_sqlite -->|"restore ledger evidence"| node_reputation
node_decision -->|"blocked outcome"| node_feedback
node_feedback -->|"receiver/device evidence"| node_reputation
node_synthetic_data -->|"enriched training data"| node_training_pipeline
node_training_pipeline -->|"serialize serving artifacts"| node_model_artifacts
node_runtime_dependencies -.->|"serves runtime"| node_api
node_runtime_dependencies -.->|"trains models"| node_training_pipeline

click node_simulator "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/iobpay/index.html"
click node_dashboard "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/dashboard/app.py"
click node_api "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py"
click node_decision "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py"
click node_sqlite "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/db.py"
click node_trust "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/trust_engine.py"
click node_reputation "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/reputation.py"
click node_feedback "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py"
click node_synthetic_data "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/data/generate_synthetic.py"
click node_training_pipeline "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/train_pipeline.py"
click node_runtime_dependencies "https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_simulator,node_dashboard toneBlue
class node_api,node_decision,node_model_artifacts,node_sqlite toneAmber
class node_trust,node_reputation,node_feedback toneMint
class node_synthetic_data,node_training_pipeline,node_runtime_dependencies toneRose
```

## Components

### User clients

- [IOB Pay simulator](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/iobpay/index.html): Static React client · Creates simulated payment profiles and displays decisions. · `iobpay/index.html`
- [Analyst dashboard](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/dashboard/app.py): Streamlit client · Investigates history, explanations, reports, and ledger state. · `dashboard/app.py`

### Serving runtime

- [PayGuard API](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py): FastAPI service · Central HTTP runtime for scoring, history, reputation, trust, and governance. · `api/main.py`
- [Risk decision composer](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py): Decision layer · Blends model and stateful signals into 0–100 risk and outcome. · `api/main.py`
- **Serialized ML artifacts**: Inference artifacts · LightGBM, Isolation Forest, scaler, feature schema, and SHAP explainer.
- [SQLite state store](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/db.py): SQLite database · Durable transactions, trust history, and reputation ledger. · `models/db.py`

### Risk intelligence

- [Customer trust engine](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/trust_engine.py): History signal · Maintains durable customer trust separately from transaction risk. · `models/trust_engine.py`
- [Reputation ledger](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/reputation.py): Escalation signal · Tracks receiver and device evidence; bad entities can escalate outcomes. · `models/reputation.py`
- [Fraud-memory feedback](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/api/main.py): State update · Blocked payments add receiver and device evidence for future scoring. · `api/main.py`

### Training pipeline

- [Synthetic data generation](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/data/generate_synthetic.py): Data preparation · Enriches fraud data with behavioral, device, and session features. · `data/generate_synthetic.py`
- [Model training pipeline](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/models/train_pipeline.py): ML training · Trains models and serializes inference metadata and explainers. · `models/train_pipeline.py`
- [Python runtime dependencies](https://github.com/rajaramanpa/fraud-prevention-detection-system/blob/main/requirements.txt): Dependencies · FastAPI, Streamlit, ML libraries, SHAP, Plotly, and SQLite support. · `requirements.txt`

## Connections

- 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