# bhaavinjain/real-time-financial-fraud-detection-system architecture

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

- Interactive diagram: https://gitdiagram.com/bhaavinjain/real-time-financial-fraud-detection-system
- Repository: https://github.com/bhaavinjain/real-time-financial-fraud-detection-system

## Overview

This is a real-time transaction fraud detection product: transactions enter through the Streamlit analyst dashboard or the FastAPI prediction API, are validated and transformed, scored by an XGBoost/autoencoder ensemble, and returned with a fraud verdict and SHAP explanation. The dashboard supports batch review, a quick demo, and model-performance reporting; the API also exposes health and running metrics. The graph follows the documented deployment and prediction flow. Model-training and notebook internals are not sampled, so their details are not expanded.

Main entry points: [`api/main.py`](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/main.py) (FastAPI service), [`dashboard/app.py`](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py) (Dashboard), [`api/schemas.py`](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/schemas.py) (Input and output schemas), [`api/preprocessing.py`](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/preprocessing.py) (Feature preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_batch["Batch review<br/>[app.py]"]
  node_quick_demo["Quick demo<br/>[app.py]"]
  node_performance["Model performance<br/>[app.py]"]
end

subgraph group_serving["API serving"]
  node_api["FastAPI service<br/>[main.py]"]
  node_schemas["Input and output schemas<br/>[schemas.py]"]
  node_health_metrics["Health and metrics<br/>[main.py]"]
end

subgraph group_inference["Inference pipeline"]
  node_preprocess["Feature preparation<br/>[preprocessing.py]"]
  node_xgb["XGBoost classifier<br/>[xgboost_best.pkl]"]
  node_autoencoder["Anomaly scoring<br/>[autoencoder.keras]"]
  node_ensemble["Ensemble decision"]
  node_explain["SHAP explanation<br/>[shap_explainer.pkl]"]
end

subgraph group_artifacts["Model artifacts"]
  node_inference_assets["Inference assets"]
end

node_analyst(("Fraud analyst"))
node_payment_processor(("Payment processor"))

node_analyst -->|"uses"| node_dashboard
node_payment_processor -.->|"submits transactions"| node_api
node_dashboard -->|"sends HTTPS requests"| node_api
node_dashboard -->|"offers"| node_batch
node_dashboard -->|"offers"| node_quick_demo
node_dashboard -->|"offers"| node_performance
node_batch -->|"requests scores"| node_api
node_quick_demo -->|"requests score"| node_api
node_dashboard -->|"reads status"| node_health_metrics
node_api -->|"validates and returns"| node_schemas
node_api -->|"engineers and encodes"| node_preprocess
node_api -->|"predicts probability"| node_xgb
node_api -->|"computes reconstruction"| node_autoencoder
node_api -->|"calculates verdict"| node_ensemble
node_api -->|"computes SHAP values"| node_explain
node_api -->|"loads at startup"| node_inference_assets
node_api -->|"serves endpoints"| node_health_metrics

click node_dashboard "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py"
click node_api "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/main.py"
click node_schemas "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/schemas.py"
click node_preprocess "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/preprocessing.py"
click node_xgb "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/xgboost_best.pkl"
click node_autoencoder "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/autoencoder.keras"
click node_ensemble "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/ensemble_config.pkl"
click node_explain "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/shap_explainer.pkl"
click node_inference_assets "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/tree/main/models"
click node_batch "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py"
click node_quick_demo "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py"
click node_performance "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py"
click node_health_metrics "https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/main.py"

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_dashboard,node_batch,node_quick_demo,node_performance toneBlue
class node_api,node_schemas,node_health_metrics toneAmber
class node_preprocess,node_xgb,node_autoencoder,node_ensemble,node_explain toneMint
class node_inference_assets toneRose
class node_analyst,node_payment_processor toneIndigo
```

## Components

### User interface

- [Dashboard](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py): `dashboard/app.py`
- [Batch review](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py): `dashboard/app.py`
- [Quick demo](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py): `dashboard/app.py`
- [Model performance](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/dashboard/app.py): `dashboard/app.py`

### API serving

- [FastAPI service](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/main.py): `api/main.py`
- [Input and output schemas](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/schemas.py): `api/schemas.py`
- [Health and metrics](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/main.py): `api/main.py`

### Inference pipeline

- [Feature preparation](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/api/preprocessing.py): `api/preprocessing.py`
- [XGBoost classifier](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/xgboost_best.pkl): `models/xgboost_best.pkl`
- [Anomaly scoring](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/autoencoder.keras): `models/autoencoder.keras`
- [Ensemble decision](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/ensemble_config.pkl): `models/ensemble_config.pkl`
- [SHAP explanation](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/blob/main/models/shap_explainer.pkl): `models/shap_explainer.pkl`

### Model artifacts

- [Inference assets](https://github.com/bhaavinjain/real-time-financial-fraud-detection-system/tree/main/models): `models`

### Other components

- **Fraud analyst**
- **Payment processor**

## Connections

- Fraud analyst → Dashboard: uses (evidence: `README.md`)
- Payment processor → FastAPI service: submits transactions (evidence: `README.md`)
- Dashboard → FastAPI service: sends HTTPS requests (evidence: `README.md`)
- Dashboard → Batch review: offers (evidence: `dashboard/app.py`)
- Dashboard → Quick demo: offers (evidence: `dashboard/app.py`)
- Dashboard → Model performance: offers (evidence: `dashboard/app.py`)
- Batch review → FastAPI service: requests scores (evidence: `dashboard/app.py`)
- Quick demo → FastAPI service: requests score (evidence: `dashboard/app.py`)
- Dashboard → Health and metrics: reads status (evidence: `dashboard/app.py`)
- FastAPI service → Input and output schemas: validates and returns (evidence: `api/main.py`)
- FastAPI service → Feature preparation: engineers and encodes (evidence: `api/main.py`)
- FastAPI service → XGBoost classifier: predicts probability (evidence: `api/main.py`)
- FastAPI service → Anomaly scoring: computes reconstruction (evidence: `api/main.py`)
- FastAPI service → Ensemble decision: calculates verdict (evidence: `api/main.py`)
- FastAPI service → SHAP explanation: computes SHAP values (evidence: `api/main.py`)
- FastAPI service → Inference assets: loads at startup (evidence: `api/main.py`)
- FastAPI service → Health and metrics: serves endpoints (evidence: `api/main.py`)
