# susai23/fraud-detection-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/susai23/fraud-detection-pipeline
- Repository: https://github.com/susai23/fraud-detection-pipeline

## Overview

This repository combines a Streamlit insurance-claims investigation assistant with a scaffolded fraud-model pipeline. The user workflow is claim entry → fraud scoring → SHAP explanations → retrieval-grounded investigation note. Separately, the documented batch workflow loads raw data, preprocesses it, engineers features, trains a model, evaluates a holdout, and scores new data. The README calls the pipeline a scaffold, and feature wiring is explicitly unfinished. The app’s runtime integrations are visible in app.py; unsampled configuration and enrichment wiring is not inferred.

Main entry points: [`app.py`](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py) (Claim entry and results), [`src/config.py`](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/config.py) (Pipeline configuration), [`models/trained_models.pkl`](https://github.com/susai23/fraud-detection-pipeline/blob/main/models/trained_models.pkl) (Trained model artifacts), [`src/preprocessing.py`](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/preprocessing.py) (Data preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Investigation assistant"]
  node_claim_ui["Claim entry and results<br/>[app.py]"]
  node_fraud_model["Fraud scoring model<br/>[app.py]"]
  node_shap["SHAP explanations<br/>[app.py]"]
  node_guidance_retrieval["Guidance retrieval<br/>[app.py]"]
  node_guidance_store[("In-memory guidance index<br/>[app.py]")]
  node_investigation_note["Investigation note<br/>[app.py]"]
end

subgraph group_pipeline["Model pipeline"]
  node_config["Pipeline configuration<br/>[config.py]"]
  node_loader["Raw data loader<br/>[data_loader.py]"]
  node_preprocess["Data preprocessing<br/>[preprocessing.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Holdout evaluation<br/>[evaluate.py]"]
  node_prediction["Batch prediction<br/>[predict.py]"]
end

subgraph group_context["Claim context enrichment"]
  node_context_generation["UK context generation"]
  node_enrichment["Claim enrichment<br/>[enrichment.py]"]
end

subgraph group_artifacts["Data and artifacts"]
  node_raw_data["Raw transaction data"]
  node_processed_data["Processed data"]
  node_trained_models["Trained model artifacts<br/>[trained_models.pkl]"]
  node_label_encoders["Label encoder artifacts<br/>[label_encoders.pkl]"]
  node_knowledge_base["Fraud guidance text"]
  node_holdout_data["Holdout data"]
end

node_investigator(("Claims investigator"))
node_groq{{"Groq generation API"}}
node_postcode_service{{"Postcode lookup"}}
node_crime_service{{"Police crime data"}}
node_weather_service{{"Weather archive"}}

node_investigator -->|"enters claim"| node_claim_ui
node_claim_ui -->|"scores claim"| node_fraud_model
node_claim_ui -->|"explains score"| node_shap
node_claim_ui -->|"requests guidance"| node_guidance_retrieval
node_guidance_retrieval -->|"queries"| node_guidance_store
node_claim_ui -->|"renders note"| node_investigation_note
node_claim_ui -->|"requests generation"| node_groq
node_knowledge_base -->|"indexes text"| node_guidance_store
node_trained_models -->|"loads model"| node_fraud_model
node_label_encoders -->|"encodes inputs"| node_claim_ui
node_config -->|"configures"| node_loader
node_config -->|"configures"| node_preprocess
node_loader -->|"reads"| node_raw_data
node_preprocess -->|"loads raw data"| node_loader
node_preprocess -->|"writes"| node_processed_data
node_config -->|"configures"| node_training
node_processed_data -->|"reads"| node_training
node_training -->|"saves model"| node_trained_models
node_training -->|"saves split"| node_holdout_data
node_config -->|"configures"| node_evaluation
node_holdout_data -->|"reads"| node_evaluation
node_trained_models -->|"loads model"| node_evaluation
node_config -->|"configures"| node_prediction
node_prediction -->|"calls preprocessing"| node_preprocess
node_trained_models -->|"loads model"| node_prediction
node_enrichment -->|"looks up coordinates"| node_postcode_service
node_enrichment -->|"fetches crime data"| node_crime_service
node_enrichment -->|"fetches weather"| node_weather_service

click node_claim_ui "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_fraud_model "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_shap "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_guidance_retrieval "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_guidance_store "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_investigation_note "https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py"
click node_config "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/config.py"
click node_loader "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/data_loader.py"
click node_preprocess "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/preprocessing.py"
click node_features "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/features.py"
click node_training "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/train.py"
click node_evaluation "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/evaluate.py"
click node_prediction "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/predict.py"
click node_context_generation "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/uk_context_generator.py"
click node_enrichment "https://github.com/susai23/fraud-detection-pipeline/blob/main/src/enrichment.py"
click node_raw_data "https://github.com/susai23/fraud-detection-pipeline/tree/main/data/raw"
click node_processed_data "https://github.com/susai23/fraud-detection-pipeline/tree/main/data/processed"
click node_trained_models "https://github.com/susai23/fraud-detection-pipeline/blob/main/models/trained_models.pkl"
click node_label_encoders "https://github.com/susai23/fraud-detection-pipeline/blob/main/models/label_encoders.pkl"
click node_knowledge_base "https://github.com/susai23/fraud-detection-pipeline/blob/main/data/fraud_indicators_knowledge_base.txt"
click node_holdout_data "https://github.com/susai23/fraud-detection-pipeline/tree/main/data/processed"

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_claim_ui,node_fraud_model,node_shap,node_guidance_retrieval,node_guidance_store,node_investigation_note toneBlue
class node_config,node_loader,node_preprocess,node_features,node_training,node_evaluation,node_prediction toneAmber
class node_context_generation,node_enrichment,node_groq toneMint
class node_raw_data,node_processed_data,node_trained_models,node_label_encoders,node_knowledge_base,node_holdout_data toneRose
class node_investigator,node_postcode_service,node_crime_service,node_weather_service toneIndigo
```

## Components

### Investigation assistant

- [Claim entry and results](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`
- [Fraud scoring model](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`
- [SHAP explanations](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`
- [Guidance retrieval](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`
- [In-memory guidance index](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`
- [Investigation note](https://github.com/susai23/fraud-detection-pipeline/blob/main/app.py): `app.py`

### Model pipeline

- [Pipeline configuration](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/config.py): `src/config.py`
- [Raw data loader](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/data_loader.py): `src/data_loader.py`
- [Data preprocessing](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Feature engineering](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/features.py): `src/features.py`
- [Model training](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/train.py): `src/train.py`
- [Holdout evaluation](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/evaluate.py): `src/evaluate.py`
- [Batch prediction](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/predict.py): `src/predict.py`

### Claim context enrichment

- [UK context generation](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/uk_context_generator.py): `src/uk_context_generator.py`
- [Claim enrichment](https://github.com/susai23/fraud-detection-pipeline/blob/main/src/enrichment.py): `src/enrichment.py`

### Data and artifacts

- [Raw transaction data](https://github.com/susai23/fraud-detection-pipeline/tree/main/data/raw): `data/raw`
- [Processed data](https://github.com/susai23/fraud-detection-pipeline/tree/main/data/processed): `data/processed`
- [Trained model artifacts](https://github.com/susai23/fraud-detection-pipeline/blob/main/models/trained_models.pkl): `models/trained_models.pkl`
- [Label encoder artifacts](https://github.com/susai23/fraud-detection-pipeline/blob/main/models/label_encoders.pkl): `models/label_encoders.pkl`
- [Fraud guidance text](https://github.com/susai23/fraud-detection-pipeline/blob/main/data/fraud_indicators_knowledge_base.txt): `data/fraud_indicators_knowledge_base.txt`
- [Holdout data](https://github.com/susai23/fraud-detection-pipeline/tree/main/data/processed): `data/processed`

### Other components

- **Claims investigator**
- **Groq generation API**
- **Postcode lookup**
- **Police crime data**
- **Weather archive**

## Connections

- Claims investigator → Claim entry and results: enters claim (evidence: `app.py`)
- Claim entry and results → Fraud scoring model: scores claim (evidence: `app.py`)
- Claim entry and results → SHAP explanations: explains score (evidence: `app.py`)
- Claim entry and results → Guidance retrieval: requests guidance (evidence: `app.py`)
- Guidance retrieval → In-memory guidance index: queries (evidence: `app.py`)
- Claim entry and results → Investigation note: renders note (evidence: `app.py`)
- Claim entry and results → Groq generation API: requests generation (evidence: `app.py`)
- Fraud guidance text → In-memory guidance index: indexes text (evidence: `app.py`)
- Trained model artifacts → Fraud scoring model: loads model (evidence: `app.py`)
- Label encoder artifacts → Claim entry and results: encodes inputs (evidence: `app.py`)
- Pipeline configuration → Raw data loader: configures (evidence: `src/data_loader.py`)
- Pipeline configuration → Data preprocessing: configures (evidence: `src/preprocessing.py`)
- Raw data loader → Raw transaction data: reads (evidence: `src/data_loader.py`)
- Data preprocessing → Raw data loader: loads raw data (evidence: `src/preprocessing.py`)
- Data preprocessing → Processed data: writes (evidence: `src/preprocessing.py`)
- Pipeline configuration → Model training: configures (evidence: `src/train.py`)
- Processed data → Model training: reads (evidence: `src/train.py`)
- Model training → Trained model artifacts: saves model (evidence: `src/train.py`)
- Model training → Holdout data: saves split (evidence: `src/train.py`)
- Pipeline configuration → Holdout evaluation: configures (evidence: `src/evaluate.py`)
- Holdout data → Holdout evaluation: reads (evidence: `src/evaluate.py`)
- Trained model artifacts → Holdout evaluation: loads model (evidence: `src/evaluate.py`)
- Pipeline configuration → Batch prediction: configures (evidence: `src/predict.py`)
- Batch prediction → Data preprocessing: calls preprocessing (evidence: `src/predict.py`)
- Trained model artifacts → Batch prediction: loads model (evidence: `src/predict.py`)
- Claim enrichment → Postcode lookup: looks up coordinates (evidence: `src/enrichment.py`)
- Claim enrichment → Police crime data: fetches crime data (evidence: `src/enrichment.py`)
- Claim enrichment → Weather archive: fetches weather (evidence: `src/enrichment.py`)
