# aathisankar7/fraud-detection-versioned architecture

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

- Interactive diagram: https://gitdiagram.com/aathisankar7/fraud-detection-versioned
- Repository: https://github.com/aathisankar7/fraud-detection-versioned

## Overview

This is a DuckDB/XGBoost fraud-detection project, developed through four progressively more realistic and capable model versions. Its main workflow builds customer profiles and transaction-level model inputs, trains and evaluates a classifier, then—in V4—saves a model used by an interactive fraud assistant to score an account and request an analyst-friendly explanation from an Ollama model. The README documents the version stages; sampled source confirms V4 feature construction, training, and assistant behavior. Some earlier-stage links rely on README descriptions rather than sampled implementations.

Main entry points: [`langchain/Fraud_assistant.py`](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/langchain/Fraud_assistant.py) (Account Fraud Assistant), [`src/v4_improved/02_final_model.py`](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v4_improved/02_final_model.py) (Oversampled Trainer), [`src/v1_baseline/02_setup_duckdb.py`](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/02_setup_duckdb.py) (Baseline Database), [`src/v1_baseline/03_profile_duckdb.py`](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/03_profile_duckdb.py) (Customer Profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v1["V1 Baseline"]
  node_v1db[("Baseline Database<br/>[02_setup_duckdb.py]")]
  node_v1profile["Customer Profile"]
  node_v1advanced["Advanced Profile"]
  node_v1input["Baseline Features<br/>[05_model_input.py]"]
  node_v1model["Baseline Model<br/>[06_xg_boost.py]"]
end

subgraph group_v2["V2 Hardened"]
  node_v2db[("Hardened Database<br/>[02_setup_duckdb.py]")]
  node_v2profile["Customer Profile"]
  node_v2advanced["Advanced Profile"]
  node_v2input["Hardened Features<br/>[05_model_input.py]"]
  node_v2model["Hardened Model<br/>[06_xg_boost.py]"]
end

subgraph group_v3["V3 Feature Upgrade"]
  node_v3input["Engineered Features"]
  node_v3model["Feature Model<br/>[02_xg_boost.py]"]
end

subgraph group_v4["V4 Scoring"]
  node_v4input["SQL Feature Builder"]
  node_v4model["Oversampled Trainer<br/>[02_final_model.py]"]
  node_modelartifact["Trained Model<br/>[fraud_v4.pkl]"]
  node_encoderartifact["Label Encoders<br/>[encoders.pkl]"]
  node_assistant["Account Fraud Assistant<br/>[Fraud_assistant.py]"]
end

node_analyst(("Fraud Analyst"))
node_transactions["Transaction Data"]
node_ollama{{"Ollama LLM"}}

node_transactions -->|"loads data"| node_v1db
node_v1db -->|"profiles"| node_v1profile
node_v1profile -->|"extends profile"| node_v1advanced
node_v1advanced -->|"builds features"| node_v1input
node_v1input -->|"trains on"| node_v1model
node_transactions -->|"loads data"| node_v2db
node_v2db -->|"profiles"| node_v2profile
node_v2profile -->|"extends profile"| node_v2advanced
node_v2advanced -->|"builds features"| node_v2input
node_v2input -->|"trains on"| node_v2model
node_transactions -->|"reads transactions"| node_v3input
node_v3input -->|"trains on"| node_v3model
node_transactions -->|"reads transactions"| node_v4input
node_v4input -->|"trains on"| node_v4model
node_v4model -->|"saves model"| node_modelartifact
node_v4model -->|"saves encoders"| node_encoderartifact
node_analyst -->|"enters account"| node_assistant
node_assistant -->|"scores with"| node_modelartifact
node_assistant -->|"encodes features"| node_encoderartifact
node_assistant -->|"requests explanation"| node_ollama

click node_v1db "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/02_setup_duckdb.py"
click node_v1profile "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/03_profile_duckdb.py"
click node_v1advanced "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/04_advanced_profiling.py"
click node_v1input "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/05_model_input.py"
click node_v1model "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/06_xg_boost.py"
click node_v2db "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/02_setup_duckdb.py"
click node_v2profile "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/03_profile_duckdb.py"
click node_v2advanced "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/04_advanced_profiling.py"
click node_v2input "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/05_model_input.py"
click node_v2model "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/06_xg_boost.py"
click node_v3input "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v3_feature_upgrade/01_model_input_v3.py"
click node_v3model "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v3_feature_upgrade/02_xg_boost.py"
click node_v4input "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v4_improved/01_model_input_final.py"
click node_v4model "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v4_improved/02_final_model.py"
click node_modelartifact "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/model/fraud_v4.pkl"
click node_encoderartifact "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/model/encoders.pkl"
click node_assistant "https://github.com/aathisankar7/fraud-detection-versioned/blob/main/langchain/Fraud_assistant.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_v1db,node_v1profile,node_v1advanced,node_v1input,node_v1model toneBlue
class node_v2db,node_v2profile,node_v2advanced,node_v2input,node_v2model toneAmber
class node_v3input,node_v3model toneMint
class node_v4input,node_v4model,node_modelartifact,node_encoderartifact,node_assistant toneRose
class node_analyst,node_transactions,node_ollama toneIndigo
```

## Components

### V1 Baseline

- [Baseline Database](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/02_setup_duckdb.py): `src/v1_baseline/02_setup_duckdb.py`
- [Customer Profile](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/03_profile_duckdb.py): `src/v1_baseline/03_profile_duckdb.py`
- [Advanced Profile](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/04_advanced_profiling.py): `src/v1_baseline/04_advanced_profiling.py`
- [Baseline Features](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/05_model_input.py): `src/v1_baseline/05_model_input.py`
- [Baseline Model](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v1_baseline/06_xg_boost.py): `src/v1_baseline/06_xg_boost.py`

### V2 Hardened

- [Hardened Database](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/02_setup_duckdb.py): `src/v2_hardened/02_setup_duckdb.py`
- [Customer Profile](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/03_profile_duckdb.py): `src/v2_hardened/03_profile_duckdb.py`
- [Advanced Profile](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/04_advanced_profiling.py): `src/v2_hardened/04_advanced_profiling.py`
- [Hardened Features](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/05_model_input.py): `src/v2_hardened/05_model_input.py`
- [Hardened Model](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v2_hardened/06_xg_boost.py): `src/v2_hardened/06_xg_boost.py`

### V3 Feature Upgrade

- [Engineered Features](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v3_feature_upgrade/01_model_input_v3.py): `src/v3_feature_upgrade/01_model_input_v3.py`
- [Feature Model](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v3_feature_upgrade/02_xg_boost.py): `src/v3_feature_upgrade/02_xg_boost.py`

### V4 Scoring

- [SQL Feature Builder](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v4_improved/01_model_input_final.py): `src/v4_improved/01_model_input_final.py`
- [Oversampled Trainer](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/src/v4_improved/02_final_model.py): `src/v4_improved/02_final_model.py`
- [Trained Model](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/model/fraud_v4.pkl): `model/fraud_v4.pkl`
- [Label Encoders](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/model/encoders.pkl): `model/encoders.pkl`
- [Account Fraud Assistant](https://github.com/aathisankar7/fraud-detection-versioned/blob/main/langchain/Fraud_assistant.py): `langchain/Fraud_assistant.py`

### Other components

- **Fraud Analyst**
- **Transaction Data**
- **Ollama LLM**

## Connections

- Transaction Data → Baseline Database: loads data (evidence: `README.md`)
- Baseline Database → Customer Profile: profiles (evidence: `README.md`)
- Customer Profile → Advanced Profile: extends profile (evidence: `README.md`)
- Advanced Profile → Baseline Features: builds features (evidence: `README.md`)
- Baseline Features → Baseline Model: trains on (evidence: `README.md`)
- Transaction Data → Hardened Database: loads data (evidence: `README.md`)
- Hardened Database → Customer Profile: profiles (evidence: `README.md`)
- Customer Profile → Advanced Profile: extends profile (evidence: `README.md`)
- Advanced Profile → Hardened Features: builds features (evidence: `README.md`)
- Hardened Features → Hardened Model: trains on (evidence: `README.md`)
- Transaction Data → Engineered Features: reads transactions (evidence: `src/v3_feature_upgrade/01_model_input_v3.py`)
- Engineered Features → Feature Model: trains on (evidence: `src/v3_feature_upgrade/02_xg_boost.py`)
- Transaction Data → SQL Feature Builder: reads transactions (evidence: `src/v4_improved/01_model_input_final.py`)
- SQL Feature Builder → Oversampled Trainer: trains on (evidence: `src/v4_improved/02_final_model.py`)
- Oversampled Trainer → Trained Model: saves model (evidence: `src/v4_improved/02_final_model.py`)
- Oversampled Trainer → Label Encoders: saves encoders (evidence: `src/v4_improved/02_final_model.py`)
- Fraud Analyst → Account Fraud Assistant: enters account (evidence: `langchain/Fraud_assistant.py`)
- Account Fraud Assistant → Trained Model: scores with (evidence: `langchain/Fraud_assistant.py`)
- Account Fraud Assistant → Label Encoders: encodes features (evidence: `langchain/Fraud_assistant.py`)
- Account Fraud Assistant → Ollama LLM: requests explanation (evidence: `langchain/Fraud_assistant.py`)
