# singhjatin3078-max/supply-chain-fraud-detection architecture

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

- Interactive diagram: https://gitdiagram.com/singhjatin3078-max/supply-chain-fraud-detection
- Repository: https://github.com/singhjatin3078-max/supply-chain-fraud-detection

## Overview

#### Purpose and Entry Points
This repository detects supply-chain fraud by turning transactional/entity data into graphs, scoring suspicious behavior, and presenting results through a Python app. Primary execution surfaces are `app.py` for the interactive interface, `gnn model.py` for GNN-related training/model work, and `src/simulate_federated_demo.py` for federated demonstrations.

#### Data Preparation and Graph Construction
Raw or generated supply-chain data is created or sourced under `data/`, then normalized into graph-ready representations. `src/data_processor.py` is the processing boundary for input records; `src/graph_builder.py` creates the entity/transaction graph consumed by detection and visualization stages. `data/generate_data.py` supports synthetic/demo data generation.

#### Fraud Detection Layer
`src/fraud_detector.py` encapsulates fraud-scoring/detection logic over processed graph or transaction data. The separate `gnn model.py` is the model-oriented entry point for graph neural network training or inference. This separates data/graph mechanics from model scoring, although the exact framework is not established by the supplied tree.

#### Application and Visualization
`app.py` is the deployment-facing Python application, intended for inference and visualization. `src/visualizer.py` provides graph/result visualization support; bundled browser assets in `lib/vis-9.1.2/` and `lib/tom-select/` indicate that interactive graph or selection UI assets may be served or embedded by the app. The README identifies Streamlit Community Cloud as a target deployment environment.

#### Federated Detection Workflow
Federated coordination is represented by `src/federated_node.py` and orchestrated in `src/simulate_federated_demo.py`. The likely control flow is: each participant processes local supply-chain data, performs local detection/model work, and contributes a shareable result rather than exposing all raw inputs. This is a key privacy/trust boundary between participant-local processing and federation-wide intelligence.

#### Blockchain Registry and Integrity Boundary
A Solidity registry, `blockchain/contracts/FederatedThreatRegistry.sol`, provides an on-chain component for federated threat records. Python integration is isolated in `src/blockchain_client.py`; proof-related logic is in `src/merkle_proof.py`. Deployment is handled through Hardhat scripts at `blockchain/scripts/deploy.js` and `blockchain/scripts/deploy_federated.js`, with deployed contract addresses recorded in `src/contracts/deployed_addresses.json`. This boundary connects Python detection/federation outputs to an Ethereum-compatible contract rather than making blockchain part of core model execution.

#### Runtime and Delivery
The main runtime is Python, with dependencies declared in `requirements.txt`; the app is intended to run directly or under Streamlit deployment. Smart-contract development uses Node.js/Hardhat, defined by `blockchain/package.json` and `blockchain/hardhat.config.js`. CI is configured in `.github/workflows/ci.yml`. The architecture therefore spans local Python analytics/UI, optional federated simulation, and a separately deployable EVM registry.

Main entry points: [`app.py`](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/app.py) (Interactive app), [`src/federated_node.py`](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/federated_node.py) (Federated node), [`src/blockchain_client.py`](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/blockchain_client.py) (Blockchain client), [`src/graph_builder.py`](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/graph_builder.py) (Graph builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data & Detection"]
  node_data_generation["Synthetic data generator<br/>Python generator<br/>[generate_data.py]"]
  node_data_store[("Supply-chain data<br/>data files")]
  node_processor["Data processor<br/>Python processing<br/>[data_processor.py]"]
  node_graph_builder["Graph builder<br/>Python graph construction<br/>[graph_builder.py]"]
  node_fraud_detector["Fraud detector<br/>Python scoring<br/>[fraud_detector.py]"]
  node_gnn_model{{"GNN model<br/>Python model entry point<br/>[gnn model.py]"}}
end

subgraph group_app["Application"]
  node_app_entry["Interactive app<br/>Python application<br/>[app.py]"]
  node_visualizer["Result visualizer<br/>Python visualization<br/>[visualizer.py]"]
end

subgraph group_federation["Federated Workflow"]
  node_federated_demo["Federated demo<br/>Python orchestration"]
  node_federated_node["Federated node<br/>Python participant<br/>[federated_node.py]"]
end

subgraph group_blockchain["Integrity Registry"]
  node_merkle_proof["Merkle proofs<br/>Python proof logic<br/>[merkle_proof.py]"]
  node_blockchain_client["Blockchain client<br/>Python integration"]
  node_threat_registry[("Federated threat registry<br/>Solidity contract")]
  node_contract_addresses["Deployed addresses<br/>contract metadata"]
  node_deployment_script["Federated deployment<br/>Hardhat script"]
end

subgraph group_delivery["Runtime &amp; Delivery"]
  node_python_dependencies["Python runtime<br/>dependency manifest<br/>[requirements.txt]"]
  node_hardhat_runtime["Hardhat runtime<br/>Node.js tooling<br/>[package.json]"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
end

node_data_generation -->|"generates"| node_data_store
node_data_store -->|"input records"| node_processor
node_processor -->|"normalized data"| node_graph_builder
node_graph_builder -->|"entity/transaction graph"| node_fraud_detector
node_graph_builder -->|"graph data"| node_gnn_model
node_fraud_detector -->|"detection results"| node_app_entry
node_gnn_model -->|"model output"| node_app_entry
node_app_entry -->|"renders results"| node_visualizer
node_federated_demo -->|"orchestrates participants"| node_federated_node
node_federated_node -.->|"local input processing"| node_processor
node_federated_node -.->|"local detection"| node_fraud_detector
node_federated_node -->|"shareable threat result"| node_blockchain_client
node_merkle_proof -->|"proof material"| node_blockchain_client
node_blockchain_client -->|"registers threat record"| node_threat_registry
node_contract_addresses -->|"contract endpoint"| node_blockchain_client
node_deployment_script -->|"deploys"| node_threat_registry
node_hardhat_runtime -->|"runs"| node_deployment_script
node_python_dependencies -.->|"runtime dependencies"| node_app_entry
node_ci -.->|"validates"| node_app_entry
node_ci -.->|"validates"| node_hardhat_runtime

click node_data_generation "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/data/generate_data.py"
click node_processor "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/data_processor.py"
click node_graph_builder "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/graph_builder.py"
click node_fraud_detector "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/fraud_detector.py"
click node_gnn_model "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/gnn%20model.py"
click node_app_entry "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/app.py"
click node_visualizer "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/visualizer.py"
click node_federated_demo "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/simulate_federated_demo.py"
click node_federated_node "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/federated_node.py"
click node_merkle_proof "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/merkle_proof.py"
click node_blockchain_client "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/blockchain_client.py"
click node_threat_registry "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/contracts/FederatedThreatRegistry.sol"
click node_contract_addresses "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/contracts/deployed_addresses.json"
click node_deployment_script "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/scripts/deploy_federated.js"
click node_python_dependencies "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/requirements.txt"
click node_hardhat_runtime "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/package.json"
click node_ci "https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/.github/workflows/ci.yml"

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_data_generation,node_data_store,node_processor,node_graph_builder,node_fraud_detector,node_gnn_model toneBlue
class node_app_entry,node_visualizer toneAmber
class node_federated_demo,node_federated_node toneMint
class node_merkle_proof,node_blockchain_client,node_threat_registry,node_contract_addresses,node_deployment_script toneRose
class node_python_dependencies,node_hardhat_runtime,node_ci toneIndigo
```

## Components

### Data & Detection

- [Synthetic data generator](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/data/generate_data.py): Python generator · `data/generate_data.py`
- **Supply-chain data**: data files · Raw or generated entity and transaction records.
- [Data processor](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/data_processor.py): Python processing · Normalizes input records into graph-ready data. · `src/data_processor.py`
- [Graph builder](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/graph_builder.py): Python graph construction · Creates entity and transaction graphs. · `src/graph_builder.py`
- [Fraud detector](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/fraud_detector.py): Python scoring · Scores suspicious behavior from graph or transaction data. · `src/fraud_detector.py`
- [GNN model](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/gnn%20model.py): Python model entry point · Training or inference for graph neural network work. · `gnn model.py`

### Application

- [Interactive app](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/app.py): Python application · Deployment-facing inference and results interface. · `app.py`
- [Result visualizer](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/visualizer.py): Python visualization · Renders graph and detection results. · `src/visualizer.py`

### Federated Workflow

Participant-local analysis shares results rather than raw data.

- [Federated demo](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/simulate_federated_demo.py): Python orchestration · Orchestrates participant simulation. · `src/simulate_federated_demo.py`
- [Federated node](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/federated_node.py): Python participant · Runs local participant processing and detection. · `src/federated_node.py`

### Integrity Registry

Separately deployable EVM threat-record boundary.

- [Merkle proofs](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/merkle_proof.py): Python proof logic · `src/merkle_proof.py`
- [Blockchain client](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/blockchain_client.py): Python integration · Submits federation outputs to the registry. · `src/blockchain_client.py`
- [Federated threat registry](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/contracts/FederatedThreatRegistry.sol): Solidity contract · On-chain registry for federated threat records. · `blockchain/contracts/FederatedThreatRegistry.sol`
- [Deployed addresses](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/src/contracts/deployed_addresses.json): contract metadata · `src/contracts/deployed_addresses.json`
- [Federated deployment](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/scripts/deploy_federated.js): Hardhat script · `blockchain/scripts/deploy_federated.js`

### Runtime & Delivery

- [Python runtime](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/requirements.txt): dependency manifest · `requirements.txt`
- [Hardhat runtime](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/blockchain/package.json): Node.js tooling · Smart-contract development and deployment environment. · `blockchain/package.json`
- [CI workflow](https://github.com/singhjatin3078-max/supply-chain-fraud-detection/blob/main/.github/workflows/ci.yml): automation · `.github/workflows/ci.yml`

## Connections

- Synthetic data generator → Supply-chain data: generates
- Supply-chain data → Data processor: input records
- Data processor → Graph builder: normalized data
- Graph builder → Fraud detector: entity/transaction graph
- Graph builder → GNN model: graph data
- Fraud detector → Interactive app: detection results
- GNN model → Interactive app: model output
- Interactive app → Result visualizer: renders results
- Federated demo → Federated node: orchestrates participants
- Federated node → Data processor: local input processing
- Federated node → Fraud detector: local detection
- Federated node → Blockchain client: shareable threat result · Raw participant data remains local.
- Merkle proofs → Blockchain client: proof material
- Blockchain client → Federated threat registry: registers threat record
- Deployed addresses → Blockchain client: contract endpoint
- Federated deployment → Federated threat registry: deploys
- Hardhat runtime → Federated deployment: runs
- Python runtime → Interactive app: runtime dependencies
- CI workflow → Interactive app: validates
- CI workflow → Hardhat runtime: validates