How aryamehta26/graph-based-fraud-intelligence-platform works
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: 05_build_feature_store.py Feature store · models Model artifacts · run_analytics.py Graph analytics · 06_train_xgboost_baseline.py XGBoost base
Components 20
Data prep
Download, clean, split, and inspect AML transactions.
- AML data · Source transaction table stored under data/ after download.
data - Extract · Downloads and validates the IBM AML dataset.
notebooks/01_data_extraction.py - Clean · Cleans data, engineers features, and creates time-aware splits.
notebooks/02_data_cleaning.py - EDA · Exploratory visuals and sanity checks on prepared data.
notebooks/03_eda_visualizations.py - Parquet splits · Shared tabular output used by graph and ML pipelines.
Graph stack
Build Neo4j graph and run graph analytics.
- Graph export · Converts processed transactions into bulk-import CSVs for Neo4j.
src/graph/export_bulk_neo4j.py - Bulk load · Loads CSVs into Neo4j 5.x using bulk import and cypher support.
src/graph/bulk_load_cypher.py - Neo4j · Graph store for accounts, transactions, and relationships.
docker-compose.yml - Graph analytics · Runs degree centrality and Louvain community detection.
src/graph/run_analytics.py
Modeling
Assemble features and train fraud classifiers.
- Graph features · Pulls node-level metrics back from Neo4j for modeling.
src/models/04_extract_graph_features.py - Communities · Builds Louvain community features and related fraud-rate signals.
src/models/04b_louvain_communities.py - Feature store · Joins raw transaction features with graph-derived signals.
src/models/05_build_feature_store.py - XGBoost base · Trains the baseline fraud model on tabular features only.
src/models/06_train_xgboost_baseline.py - XGBoost graph · Trains the graph-enhanced fraud model with graph features.
src/models/07_train_graph_enhanced_model.py - Thresholding · Selects operating thresholds from precision-recall curves.
src/models/tune_threshold.py
LLM analysis
Generate and evaluate investigation reports from subgraphs.
- Investigator · Sends subgraph context to Anthropic Claude for structured reports.
src/llm/investigator.py - LLM eval · Scores schema compliance, faithfulness, and consistency.
src/llm/evaluate.py
Delivery
Dashboard and offline artifacts for analysis and demos.
- Model artifacts · Stored model JSON and metrics outputs under data/models/
data/models - Subgraphs · Precomputed subgraph JSON files used for demos and LLM analysis.
artifacts - Dashboard · User-facing interface for model metrics, graph insights, and investigations.
dashboard_app.py
Connections 24
- 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.