# piyush314159/gnn-fraudnet architecture

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

- Interactive diagram: https://gitdiagram.com/piyush314159/gnn-fraudnet
- Repository: https://github.com/piyush314159/gnn-fraudnet

## Overview

GNN-FraudNet serves transaction-fraud predictions and analyst investigations through a FastAPI API. An analyst or client submits a transaction node; the investigation agent coordinates prediction, explanation and graph analysis, then optionally retrieves fraud knowledge and generates an LLM report. The repository also includes dataset preparation, model training and evaluation capabilities. The workflow and some subsystem links are documented in the README; implementation excerpts are incomplete, so unverified links are dashed and uncited.

Main entry points: [`src/agents/investigation_agent.py`](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/agents/investigation_agent.py) (Investigation agent), [`src/llm/report_generator.py`](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/llm/report_generator.py) (LLM report generation), [`src/services/explainability.py`](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/explainability.py) (Model explanations), [`src/models/graphsage.py`](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/models/graphsage.py) (GNN and baselines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and workflow"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_agent["Investigation agent"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_ml["Data and models"]
  node_data[("Transaction graph data<br/>[data_loader.py]")]
  node_graphbuild["Graph construction<br/>[graph_builder.py]"]
  node_models["GNN and baselines<br/>[graphsage.py]"]
end

subgraph group_investigation["Investigation services"]
  node_prediction["Fraud prediction<br/>[prediction.py]"]
  node_explain["Model explanations<br/>[explainability.py]"]
  node_explainlib["SHAP utilities<br/>[explain.py]"]
  node_graphanalysis["Neighborhood analysis<br/>[graph_analysis.py]"]
  node_context["Investigation context<br/>[investigation.py]"]
end

subgraph group_knowledge["Knowledge and reports"]
  node_kb[("Fraud knowledge base<br/>[knowledge_base.py]")]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_report["LLM report generation"]
  node_prompts["Report prompts<br/>[prompts.py]"]
end

subgraph group_learning["Training and evaluation"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
end

node_analyst(("Analyst / client"))
node_llm{{"LLM provider"}}

node_analyst -->|"submits request"| node_api
node_api -->|"routes investigation"| node_agent
node_agent -->|"predicts node"| node_prediction
node_agent -->|"explains prediction"| node_explain
node_agent -->|"analyzes neighborhood"| node_graphanalysis
node_agent -->|"retrieves knowledge"| node_retriever
node_agent -.->|"generates report"| node_report
node_prediction -.->|"runs model"| node_models
node_explain -->|"runs SHAP"| node_explainlib
node_explain -->|"explains model"| node_models
node_retriever -->|"queries collection"| node_kb
node_report -->|"formats prompt"| node_prompts
node_report -->|"requests completion"| node_llm
node_report -.->|"uses retrieved context"| node_retriever
node_context -->|"requests prediction"| node_prediction
node_context -->|"requests explanation"| node_explain
node_context -->|"requests analysis"| node_graphanalysis
node_graphbuild -.->|"prepares graph"| node_data
node_training -.->|"trains on graph"| node_data
node_training -.->|"trains models"| node_models
node_evaluation -.->|"scores models"| node_models

click node_api "https://github.com/piyush314159/gnn-fraudnet/blob/main/api/main.py"
click node_agent "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/agents/investigation_agent.py"
click node_data "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/data_loader.py"
click node_graphbuild "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/graph_builder.py"
click node_prediction "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/prediction.py"
click node_models "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/models/graphsage.py"
click node_explain "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/explainability.py"
click node_explainlib "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/explain.py"
click node_graphanalysis "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/graph_analysis.py"
click node_context "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/investigation.py"
click node_kb "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/rag/knowledge_base.py"
click node_retriever "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/rag/retriever.py"
click node_report "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/llm/report_generator.py"
click node_prompts "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/llm/prompts.py"
click node_config "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/config.py"
click node_training "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/train.py"
click node_evaluation "https://github.com/piyush314159/gnn-fraudnet/blob/main/src/evaluate.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_api,node_agent,node_config,node_analyst toneBlue
class node_data,node_graphbuild,node_models toneAmber
class node_prediction,node_explain,node_explainlib,node_graphanalysis,node_context toneMint
class node_kb,node_retriever,node_report,node_prompts toneRose
class node_training,node_evaluation,node_llm toneIndigo
```

## Components

### API and workflow

- [FastAPI endpoints](https://github.com/piyush314159/gnn-fraudnet/blob/main/api/main.py): `api/main.py`
- [Investigation agent](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/agents/investigation_agent.py): `src/agents/investigation_agent.py`
- [Runtime configuration](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/config.py): `src/config.py`

### Data and models

- [Transaction graph data](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/data_loader.py): `src/data_loader.py`
- [Graph construction](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/graph_builder.py): `src/graph_builder.py`
- [GNN and baselines](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/models/graphsage.py): `src/models/graphsage.py`

### Investigation services

- [Fraud prediction](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/prediction.py): `src/services/prediction.py`
- [Model explanations](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/explainability.py): `src/services/explainability.py`
- [SHAP utilities](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/explain.py): `src/explain.py`
- [Neighborhood analysis](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/graph_analysis.py): `src/services/graph_analysis.py`
- [Investigation context](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/services/investigation.py): `src/services/investigation.py`

### Knowledge and reports

- [Fraud knowledge base](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/rag/knowledge_base.py): `src/rag/knowledge_base.py`
- [Semantic retrieval](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/rag/retriever.py): `src/rag/retriever.py`
- [LLM report generation](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/llm/report_generator.py): `src/llm/report_generator.py`
- [Report prompts](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/llm/prompts.py): `src/llm/prompts.py`

### Training and evaluation

- [Model training](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/train.py): `src/train.py`
- [Model evaluation](https://github.com/piyush314159/gnn-fraudnet/blob/main/src/evaluate.py): `src/evaluate.py`

### Other components

- **Analyst / client**
- **LLM provider**

## Connections

- Analyst / client → FastAPI endpoints: submits request (evidence: `api/main.py`)
- FastAPI endpoints → Investigation agent: routes investigation (evidence: `api/main.py`)
- Investigation agent → Fraud prediction: predicts node (evidence: `src/agents/investigation_agent.py`)
- Investigation agent → Model explanations: explains prediction (evidence: `src/agents/investigation_agent.py`)
- Investigation agent → Neighborhood analysis: analyzes neighborhood (evidence: `src/agents/investigation_agent.py`)
- Investigation agent → Semantic retrieval: retrieves knowledge (evidence: `src/agents/investigation_agent.py`)
- Investigation agent → LLM report generation: generates report (evidence: `src/agents/investigation_agent.py`)
- Fraud prediction → GNN and baselines: runs model
- Model explanations → SHAP utilities: runs SHAP (evidence: `src/services/explainability.py`)
- Model explanations → GNN and baselines: explains model (evidence: `src/services/explainability.py`)
- Semantic retrieval → Fraud knowledge base: queries collection (evidence: `src/rag/retriever.py`)
- LLM report generation → Report prompts: formats prompt (evidence: `src/llm/report_generator.py`)
- LLM report generation → LLM provider: requests completion (evidence: `src/llm/report_generator.py`)
- LLM report generation → Semantic retrieval: uses retrieved context (evidence: `src/llm/report_generator.py`)
- Investigation context → Fraud prediction: requests prediction (evidence: `src/services/investigation.py`)
- Investigation context → Model explanations: requests explanation (evidence: `src/services/investigation.py`)
- Investigation context → Neighborhood analysis: requests analysis (evidence: `src/services/investigation.py`)
- Graph construction → Transaction graph data: prepares graph
- Model training → Transaction graph data: trains on graph
- Model training → GNN and baselines: trains models
- Model evaluation → GNN and baselines: scores models