# shazfa13/fraud-detection-system architecture

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

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

## Overview

This repository is a PaySim fraud-detection project spanning exploratory analysis, past-only feature engineering, chronological Model V1 training, an HTTP prediction API, and a Kafka/Spark streaming path. The documented Phase 6 simulation warms account history before sending live requests; the streaming producer replays transactions without labels, and Spark reuses the API’s feature and model logic. The README describes streaming as not implemented, but the supplied streaming source files implement it. Notebook-stage links reflect README documentation; unsampled notebook internals are not inferred.

Main entry points: [`src/api/app.py`](https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py) (Prediction API), [`src/streaming/spark_streaming.py`](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/spark_streaming.py) (Spark stream consumer), [`notebooks/04_xgboost_model_v1.ipynb`](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/04_xgboost_model_v1.ipynb) (Model V1 training), [`src/streaming/kafka_producer.py`](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/kafka_producer.py) (Transaction producer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline modeling"]
  node_eda["Exploratory analysis"]
  node_engineering["Feature engineering"]
  node_training["Model V1 training"]
  node_deployment["API deployment"]
end

subgraph group_serving["Prediction serving"]
  node_api["Prediction API<br/>[app.py]"]
  node_account[("Account history<br/>[app.py]")]
  node_features["Feature pipeline<br/>[app.py]"]
  node_simulation["Live simulation"]
end

subgraph group_streaming["Streaming pipeline"]
  node_producer["Transaction producer<br/>[kafka_producer.py]"]
  node_streamconfig["Streaming configuration<br/>[config.py]"]
  node_bridge["Local bridge inbox"]
  node_spark["Spark stream consumer<br/>[spark_streaming.py]"]
end

subgraph group_artifacts["Data and outputs"]
  node_dataset["PaySim dataset"]
  node_model["XGBoost Model V1"]
  node_metadata["Model metadata"]
  node_threshold["Risk threshold"]
  node_predictions["Streaming predictions<br/>[config.py]"]
  node_liveoutputs["Live evaluation outputs"]
end

node_analyst(("Project analyst"))
node_client(("API client"))
node_kafka["Kafka broker"]

node_analyst -->|"explores data"| node_eda
node_dataset -.->|"analyzes"| node_eda
node_eda -.->|"informs"| node_engineering
node_engineering -.->|"produces features"| node_training
node_training -.->|"trains"| node_model
node_training -.->|"records feature names"| node_metadata
node_training -.->|"selects threshold"| node_threshold
node_deployment -->|"deploys"| node_api
node_client -->|"requests prediction"| node_api
node_api -->|"reads and updates"| node_account
node_api -->|"builds features"| node_features
node_features -->|"scores with"| node_model
node_simulation -->|"sends live requests"| node_api
node_simulation -->|"writes evaluation data"| node_liveoutputs
node_streamconfig -->|"configures"| node_producer
node_streamconfig -->|"configures"| node_spark
node_producer -->|"replays transactions"| node_dataset
node_producer -->|"publishes events"| node_kafka
node_producer -->|"writes events"| node_bridge
node_kafka -->|"streams events"| node_spark
node_bridge -->|"streams files"| node_spark
node_spark -->|"reuses feature and model logic"| node_api
node_spark -->|"appends predictions"| node_predictions

click node_eda "https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/02_exploratory_data_analysis.ipynb"
click node_engineering "https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/03_feature_engineering.ipynb"
click node_training "https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/04_xgboost_model_v1.ipynb"
click node_model "https://github.com/shazfa13/fraud-detection-system/blob/main/models/xgboost_model_v1.json"
click node_metadata "https://github.com/shazfa13/fraud-detection-system/blob/main/models/model_v1_metadata.json"
click node_threshold "https://github.com/shazfa13/fraud-detection-system/blob/main/models/model_v1_threshold.json"
click node_deployment "https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/05_model_deployment.ipynb"
click node_api "https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py"
click node_account "https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py"
click node_features "https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py"
click node_simulation "https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/06_live_transaction_simulation.ipynb"
click node_producer "https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/kafka_producer.py"
click node_streamconfig "https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/config.py"
click node_spark "https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/spark_streaming.py"
click node_predictions "https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/config.py"
click node_liveoutputs "https://github.com/shazfa13/fraud-detection-system/tree/main/reports"

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_eda,node_engineering,node_training,node_deployment,node_client toneBlue
class node_api,node_account,node_features,node_simulation toneAmber
class node_producer,node_streamconfig,node_bridge,node_spark toneMint
class node_dataset,node_model,node_metadata,node_threshold,node_predictions,node_liveoutputs toneRose
class node_analyst,node_kafka toneIndigo
```

## Components

### Offline modeling

- [Exploratory analysis](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/02_exploratory_data_analysis.ipynb): `notebooks/02_exploratory_data_analysis.ipynb`
- [Feature engineering](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/03_feature_engineering.ipynb): `notebooks/03_feature_engineering.ipynb`
- [Model V1 training](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/04_xgboost_model_v1.ipynb): `notebooks/04_xgboost_model_v1.ipynb`
- [API deployment](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/05_model_deployment.ipynb): `notebooks/05_model_deployment.ipynb`

### Prediction serving

- [Prediction API](https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py): `src/api/app.py`
- [Account history](https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py): `src/api/app.py`
- [Feature pipeline](https://github.com/shazfa13/fraud-detection-system/blob/main/src/api/app.py): `src/api/app.py`
- [Live simulation](https://github.com/shazfa13/fraud-detection-system/blob/main/notebooks/06_live_transaction_simulation.ipynb): `notebooks/06_live_transaction_simulation.ipynb`

### Streaming pipeline

- [Transaction producer](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/kafka_producer.py): `src/streaming/kafka_producer.py`
- [Streaming configuration](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/config.py): `src/streaming/config.py`
- **Local bridge inbox**
- [Spark stream consumer](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/spark_streaming.py): `src/streaming/spark_streaming.py`

### Data and outputs

- **PaySim dataset**
- [XGBoost Model V1](https://github.com/shazfa13/fraud-detection-system/blob/main/models/xgboost_model_v1.json): `models/xgboost_model_v1.json`
- [Model metadata](https://github.com/shazfa13/fraud-detection-system/blob/main/models/model_v1_metadata.json): `models/model_v1_metadata.json`
- [Risk threshold](https://github.com/shazfa13/fraud-detection-system/blob/main/models/model_v1_threshold.json): `models/model_v1_threshold.json`
- [Streaming predictions](https://github.com/shazfa13/fraud-detection-system/blob/main/src/streaming/config.py): `src/streaming/config.py`
- [Live evaluation outputs](https://github.com/shazfa13/fraud-detection-system/tree/main/reports): `reports`

### Other components

- **Project analyst**
- **API client**
- **Kafka broker**

## Connections

- Project analyst → Exploratory analysis: explores data (evidence: `README.md`)
- PaySim dataset → Exploratory analysis: analyzes
- Exploratory analysis → Feature engineering: informs
- Feature engineering → Model V1 training: produces features
- Model V1 training → XGBoost Model V1: trains
- Model V1 training → Model metadata: records feature names
- Model V1 training → Risk threshold: selects threshold
- API deployment → Prediction API: deploys (evidence: `README.md`)
- API client → Prediction API: requests prediction (evidence: `src/api/app.py`)
- Prediction API → Account history: reads and updates (evidence: `src/api/app.py`)
- Prediction API → Feature pipeline: builds features (evidence: `src/api/app.py`)
- Feature pipeline → XGBoost Model V1: scores with (evidence: `src/api/app.py`)
- Live simulation → Prediction API: sends live requests (evidence: `README.md`)
- Live simulation → Live evaluation outputs: writes evaluation data (evidence: `README.md`)
- Streaming configuration → Transaction producer: configures (evidence: `src/streaming/kafka_producer.py`)
- Streaming configuration → Spark stream consumer: configures (evidence: `src/streaming/spark_streaming.py`)
- Transaction producer → PaySim dataset: replays transactions (evidence: `src/streaming/kafka_producer.py`)
- Transaction producer → Kafka broker: publishes events (evidence: `src/streaming/kafka_producer.py`)
- Transaction producer → Local bridge inbox: writes events (evidence: `src/streaming/kafka_producer.py`)
- Kafka broker → Spark stream consumer: streams events (evidence: `src/streaming/spark_streaming.py`)
- Local bridge inbox → Spark stream consumer: streams files (evidence: `src/streaming/spark_streaming.py`)
- Spark stream consumer → Prediction API: reuses feature and model logic (evidence: `src/streaming/spark_streaming.py`)
- Spark stream consumer → Streaming predictions: appends predictions (evidence: `src/streaming/spark_streaming.py`)
