How singhjatin3078-max/supply-chain-fraud-detection works
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 Interactive app · federated_node.py Federated node · blockchain_client.py Blockchain client · graph_builder.py Graph builder
Components 18
Data & Detection
- Synthetic data generator
data/generate_data.py - Supply-chain data · Raw or generated entity and transaction records.
- Data processor · Normalizes input records into graph-ready data.
src/data_processor.py - Graph builder · Creates entity and transaction graphs.
src/graph_builder.py - Fraud detector · Scores suspicious behavior from graph or transaction data.
src/fraud_detector.py - GNN model · Training or inference for graph neural network work.
gnn model.py
Application
- Interactive app · Deployment-facing inference and results interface.
app.py - Result visualizer · Renders graph and detection results.
src/visualizer.py
Federated Workflow
Participant-local analysis shares results rather than raw data.
- Federated demo · Orchestrates participant simulation.
src/simulate_federated_demo.py - Federated node · Runs local participant processing and detection.
src/federated_node.py
Integrity Registry
Separately deployable EVM threat-record boundary.
- Merkle proofs
src/merkle_proof.py - Blockchain client · Submits federation outputs to the registry.
src/blockchain_client.py - Federated threat registry · On-chain registry for federated threat records.
blockchain/contracts/FederatedThreatRegistry.sol - Deployed addresses
src/contracts/deployed_addresses.json - Federated deployment
blockchain/scripts/deploy_federated.js
Runtime & Delivery
- Python runtime
requirements.txt - Hardhat runtime · Smart-contract development and deployment environment.
blockchain/package.json - CI workflow
.github/workflows/ci.yml
Connections 20
- 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