# aryamehta26/graph-based-fraud-intelligence-platform architecture

> Architecture diagram of the GitHub repository aryamehta26/graph-based-fraud-intelligence-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryamehta26/graph-based-fraud-intelligence-platform
- Repository: https://github.com/aryamehta26/graph-based-fraud-intelligence-platform

## Overview

1. **What the system is**
   - This repo is an end-to-end fraud intelligence platform built around one central idea: convert a large AML transaction table into a **knowledge graph**, then layer **graph analytics, machine learning, and LLM-based investigation** on top.
   - The architecture is not a single app; it is a **pipeline plus serving tools** around shared data assets.

2. **Primary data boundary**
   - The raw input is the IBM AML dataset, stored locally under `data/` after download.
   - The main handoff format through the pipeline is **Parquet** for processed tabular data and **CSV bulk-import files** for Neo4j.
   - The repo keeps trained models and run outputs in `data/models/` and `artifacts/`, while large source data is intentionally gitignored.

3. **Data extraction and cleaning layer**
   - `notebooks/01_data_extraction.py`, `02_data_cleaning.py`, and `03_eda_visualizations.py` form the data preparation stage.
   - This stage handles download, validation, cleaning, feature engineering, and **time-aware 70/15/15 splits** to avoid temporal leakage.
   - The output of this layer becomes the shared input for both the graph pipeline and the ML training pipeline.

4. **Knowledge graph construction**
   - `src/graph/export_bulk_neo4j.py` converts processed data into a strict ontology: **Account nodes, Transaction nodes, and SENT / RECEIVED_BY edges**.
   - The graph is loaded into **Neo4j 5.x** via `src/graph/bulk_load_cypher.py`, using Docker Compose for the database runtime.
   - This is a major architectural boundary: the flat transaction dataset is transformed into a graph database optimized for relationship-based analysis.

5. **Graph analytics layer**
   - `src/graph/run_analytics.py` runs **Neo4j Graph Data Science** algorithms against the account graph.
   - The current analytics used by the rest of the repo are **degree centrality** and **Louvain community detection**.
   - These graph results are not used in place of tabular features; they are exported back into the modeling pipeline as additional signals.

6. **Feature store / model input assembly**
   - `src/models/04_extract_graph_features.py` and `05_build_feature_store.py` bridge Neo4j back to the ML layer.
   - They pull node-level graph metrics, join them onto transaction rows, and create a feature store that combines:
     - raw transaction features
     - account centrality features
     - community membership / community fraud-rate features
   - This is the key integration point where graph intelligence becomes trainable model input.

7. **Fraud modeling layer**
   - `src/models/06_train_xgboost_baseline.py` trains the baseline XGBoost classifier on tabular features only.
   - `src/models/07_train_graph_enhanced_model.py` trains the enriched model using the same tabular base plus graph-derived features.
   - `src/models/tune_threshold.py` supports threshold selection from PR curves, which matters because fraud is extremely imbalanced.

8. **LLM investigation layer**
   - `src/llm/investigator.py` is a separate analysis path, not part of model scoring.
   - It consumes **precomputed subgraph JSON files** from `artifacts/` and sends them to **Anthropic Claude** to generate structured investigation reports.
   - `src/llm/evaluate.py` measures output quality across variants using schema compliance, faithfulness, and consistency.
   - This layer depends on an external API and is meant for **explanation and analyst assistance**, not automated classification.

9. **Delivery / analyst interface**
   - `dashboard_app.py` is the user-facing Streamlit dashboard.
   - It likely surfaces model metrics, graph insights, and example investigations rather than running the heavy pipeline itself.
   - The dashboard sits on top of precomputed artifacts, which keeps the serving surface lightweight and decoupled from training.

10. **Artifact and reproducibility boundaries**
   - `artifacts/` contains curated subgraphs and saved LLM outputs used for evaluation and demos.
   - `data/models/` stores trained model JSON files and metrics outputs.
   - `docker-compose.yml` is the main infrastructure entry point, defining the Neo4j environment needed for graph analytics.
   - `.env.example` indicates runtime configuration for secrets such as the Neo4j password and Anthropic API key.

11. **Repository structure as an architecture signal**
   - `notebooks/` are the data-prep and EDA orchestration layer.
   - `src/graph/` is the graph database and analytics subsystem.
   - `src/models/` is the supervised learning subsystem.
   - `src/llm/` is the investigation/reporting subsystem.
   - `dashboard_app.py` is the presentation layer that consumes outputs from the other subsystems.

12. **End-to-end flow**
   - Raw AML transactions → cleaning/feature engineering → Parquet splits → Neo4j graph load → graph analytics → feature join → XGBoost training/evaluation → threshold tuning → optional LLM investigation on flagged subgraphs → dashboard presentation.
   - The design is intentionally **multi-stage and offline-first**: heavy computation happens in batch jobs, while the dashboard and LLM analysis consume saved outputs.

Main entry points: [`src/models/05_build_feature_store.py`](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/05_build_feature_store.py) (Feature store), [`data/models`](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/data/models) (Model artifacts), [`src/graph/run_analytics.py`](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/run_analytics.py) (Graph analytics), [`src/models/06_train_xgboost_baseline.py`](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/06_train_xgboost_baseline.py) (XGBoost base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data prep"]
  node_raw_aml[("AML data<br/>raw dataset")]
  node_extract["Extract<br/>prep stage"]
  node_clean["Clean<br/>prep stage"]
  node_eda["EDA<br/>analysis stage"]
  node_parquet[("Parquet splits<br/>processed data")]
end

subgraph group_graph["Graph stack"]
  node_neo4j_export["Graph export<br/>neo4j export"]
  node_bulk_load["Bulk load<br/>neo4j load"]
  node_neo4j_db[("Neo4j<br/>graph database<br/>[docker-compose.yml]")]
  node_analytics["Graph analytics<br/>gds jobs<br/>[run_analytics.py]"]
end

subgraph group_ml["Modeling"]
  node_graph_features["Graph features<br/>feature extraction"]
  node_communities["Communities<br/>feature enrichment"]
  node_feature_store["Feature store<br/>ml inputs"]
  node_baseline["XGBoost base<br/>classifier"]
  node_enhanced["XGBoost graph<br/>classifier"]
  node_threshold["Thresholding<br/>calibration<br/>[tune_threshold.py]"]
end

subgraph group_llm["LLM analysis"]
  node_investigator["Investigator<br/>llm pipeline<br/>[investigator.py]"]
  node_llm_eval["LLM eval<br/>evaluation<br/>[evaluate.py]"]
end

subgraph group_serve["Delivery"]
  node_models_out[("Model artifacts<br/>saved models")]
  node_subgraphs[("Subgraphs<br/>curated artifacts")]
  node_dashboard["Dashboard<br/>streamlit app<br/>[dashboard_app.py]"]
end

node_raw_aml -->|"source data"| node_extract
node_extract -->|"validate"| node_clean
node_clean -->|"write"| node_parquet
node_parquet -.->|"inspect"| node_eda
node_parquet -->|"transform"| node_neo4j_export
node_neo4j_export -->|"bulk csvs"| node_bulk_load
node_bulk_load -->|"populate"| node_neo4j_db
node_neo4j_db -->|"run gds"| node_analytics
node_analytics -->|"export metrics"| node_graph_features
node_analytics -->|"community data"| node_communities
node_graph_features -->|"join"| node_feature_store
node_communities -->|"enrich"| node_feature_store
node_parquet -->|"base inputs"| node_feature_store
node_feature_store -->|"train"| node_baseline
node_feature_store -->|"train"| node_enhanced
node_baseline -.->|"calibrate"| node_threshold
node_enhanced -.->|"calibrate"| node_threshold
node_baseline -->|"save"| node_models_out
node_enhanced -->|"save"| node_models_out
node_models_out -.->|"display"| node_dashboard
node_subgraphs -->|"prompt"| node_investigator
node_investigator -->|"measure"| node_llm_eval
node_llm_eval -.->|"surface"| node_dashboard
node_models_out -.->|"flag cases"| node_subgraphs

click node_raw_aml "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/data"
click node_extract "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/01_data_extraction.py"
click node_clean "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/02_data_cleaning.py"
click node_eda "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/03_eda_visualizations.py"
click node_neo4j_export "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/export_bulk_neo4j.py"
click node_bulk_load "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/bulk_load_cypher.py"
click node_neo4j_db "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/docker-compose.yml"
click node_analytics "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/run_analytics.py"
click node_graph_features "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/04_extract_graph_features.py"
click node_communities "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/04b_louvain_communities.py"
click node_feature_store "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/05_build_feature_store.py"
click node_baseline "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/06_train_xgboost_baseline.py"
click node_enhanced "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/07_train_graph_enhanced_model.py"
click node_threshold "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/tune_threshold.py"
click node_models_out "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/data/models"
click node_subgraphs "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/artifacts"
click node_investigator "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/llm/investigator.py"
click node_llm_eval "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/llm/evaluate.py"
click node_dashboard "https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/dashboard_app.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_raw_aml,node_extract,node_clean,node_eda,node_parquet toneBlue
class node_neo4j_export,node_bulk_load,node_neo4j_db,node_analytics toneAmber
class node_graph_features,node_communities,node_feature_store,node_baseline,node_enhanced,node_threshold toneMint
class node_investigator,node_llm_eval toneRose
class node_models_out,node_subgraphs,node_dashboard toneIndigo
```

## Components

### Data prep

Download, clean, split, and inspect AML transactions.

- [AML data](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/data): raw dataset · Source transaction table stored under data/ after download. · `data`
- [Extract](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/01_data_extraction.py): prep stage · Downloads and validates the IBM AML dataset. · `notebooks/01_data_extraction.py`
- [Clean](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/02_data_cleaning.py): prep stage · Cleans data, engineers features, and creates time-aware splits. · `notebooks/02_data_cleaning.py`
- [EDA](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/notebooks/03_eda_visualizations.py): analysis stage · Exploratory visuals and sanity checks on prepared data. · `notebooks/03_eda_visualizations.py`
- **Parquet splits**: processed data · Shared tabular output used by graph and ML pipelines.

### Graph stack

Build Neo4j graph and run graph analytics.

- [Graph export](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/export_bulk_neo4j.py): neo4j export · Converts processed transactions into bulk-import CSVs for Neo4j. · `src/graph/export_bulk_neo4j.py`
- [Bulk load](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/bulk_load_cypher.py): neo4j load · Loads CSVs into Neo4j 5.x using bulk import and cypher support. · `src/graph/bulk_load_cypher.py`
- [Neo4j](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/docker-compose.yml): graph database · Graph store for accounts, transactions, and relationships. · `docker-compose.yml`
- [Graph analytics](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/graph/run_analytics.py): gds jobs · Runs degree centrality and Louvain community detection. · `src/graph/run_analytics.py`

### Modeling

Assemble features and train fraud classifiers.

- [Graph features](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/04_extract_graph_features.py): feature extraction · Pulls node-level metrics back from Neo4j for modeling. · `src/models/04_extract_graph_features.py`
- [Communities](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/04b_louvain_communities.py): feature enrichment · Builds Louvain community features and related fraud-rate signals. · `src/models/04b_louvain_communities.py`
- [Feature store](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/05_build_feature_store.py): ml inputs · Joins raw transaction features with graph-derived signals. · `src/models/05_build_feature_store.py`
- [XGBoost base](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/06_train_xgboost_baseline.py): classifier · Trains the baseline fraud model on tabular features only. · `src/models/06_train_xgboost_baseline.py`
- [XGBoost graph](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/07_train_graph_enhanced_model.py): classifier · Trains the graph-enhanced fraud model with graph features. · `src/models/07_train_graph_enhanced_model.py`
- [Thresholding](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/models/tune_threshold.py): calibration · Selects operating thresholds from precision-recall curves. · `src/models/tune_threshold.py`

### LLM analysis

Generate and evaluate investigation reports from subgraphs.

- [Investigator](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/llm/investigator.py): llm pipeline · Sends subgraph context to Anthropic Claude for structured reports. · `src/llm/investigator.py`
- [LLM eval](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/src/llm/evaluate.py): evaluation · Scores schema compliance, faithfulness, and consistency. · `src/llm/evaluate.py`

### Delivery

Dashboard and offline artifacts for analysis and demos.

- [Model artifacts](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/data/models): saved models · Stored model JSON and metrics outputs under data/models/ · `data/models`
- [Subgraphs](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/tree/main/artifacts): curated artifacts · Precomputed subgraph JSON files used for demos and LLM analysis. · `artifacts`
- [Dashboard](https://github.com/aryamehta26/graph-based-fraud-intelligence-platform/blob/main/dashboard_app.py): streamlit app · User-facing interface for model metrics, graph insights, and investigations. · `dashboard_app.py`

## Connections

- AML data → Extract: source data · Raw AML transactions are the input to extraction.
- Extract → Clean: validate · Downloaded data is validated and prepared for cleaning.
- Clean → Parquet splits: write · Cleaning and feature engineering produce split parquet datasets.
- Parquet splits → EDA: inspect · Prepared data is used for exploratory analysis.
- Parquet splits → Graph export: transform · Processed transactions are converted into graph import files.
- Graph export → Bulk load: bulk csvs · Exported CSVs are loaded into Neo4j.
- Bulk load → Neo4j: populate · Bulk load populates the graph database.
- Neo4j → Graph analytics: run gds · Graph Data Science algorithms execute against Neo4j.
- Graph analytics → Graph features: export metrics · Computed graph metrics are brought back into the ML layer.
- Graph analytics → Communities: community data · Community assignments and fraud-rate signals are derived from graph output.
- Graph features → Feature store: join · Graph metrics are joined onto transaction rows.
- Communities → Feature store: enrich · Community features are added to the feature store.
- Parquet splits → Feature store: base inputs · Tabular transaction features feed the shared model inputs.
- Feature store → XGBoost base: train · Baseline model uses tabular features only.
- Feature store → XGBoost graph: train · Graph-enhanced model uses the enriched feature store.
- XGBoost base → Thresholding: calibrate · Threshold tuning uses classifier outputs and PR curves.
- XGBoost graph → Thresholding: calibrate · Threshold tuning selects the operating point for fraud detection.
- XGBoost base → Model artifacts: save · Baseline model and metrics are persisted.
- XGBoost graph → Model artifacts: save · Graph-enhanced model and metrics are persisted.
- Model artifacts → Dashboard: display · Saved metrics and model comparisons feed the dashboard.
- Subgraphs → Investigator: prompt · Curated subgraphs are analyzed by the LLM investigator.
- Investigator → LLM eval: measure · Generated reports are evaluated for quality and consistency.
- LLM eval → Dashboard: surface · Evaluation results and example investigations can be shown in the dashboard.
- Model artifacts → Subgraphs: flag cases · Model artifacts support selection of examples for LLM investigation.