AI-powered full-stack platform predicting global supply chain disruptions using a Multi-Modal Hybrid Deep Learning framework — combining BERT, LSTM, Temporal Fusion Transformer, Graph Attention Networks, and Variational Autoencoders. Features a real-time React dashboard with live world risk map, geopolitical event monitoring (Iran–Israel conflict, Strait of Hormuz, Red Sea / Houthi crisis), and intelligent actionable recommendations.
- Overview
- Live Features
- AI Architecture
- Tech Stack
- Project Structure
- Quick Start
- API Reference
- Research Foundation
- Data Sources
- Troubleshooting
- Academic Context
ChainGuard AI addresses one of the most critical problems in global trade — predicting supply chain disruptions before they cause damage. The platform fuses three distinct data modalities through a unified AI framework and surfaces risk intelligence through a production-grade dashboard.
| Event | Impact | ChainGuard Signal |
|---|---|---|
| Iran–Israel Escalation (2024) | LPG prices spiked +18%, Hormuz threatened | Iran tension score + Hormuz risk index |
| Red Sea / Houthi Crisis (2023–24) | 30% of container traffic rerouted, freight +300% | Freight rate spike + Red Sea alert feed |
| COVID-19 Semiconductor Shortage | $190B+ manufacturing losses globally | Multi-tier supplier graph vulnerability |
| Ever Given Suez Blockage (2021) | $9.6B/day global trade halted for 6 days | Anomaly detection (VAE black-swan module) |
| Russia–Ukraine Conflict | Grain + energy supply disruption | Geopolitical conflict encoding |
💡 Average cost of one supply chain disruption to a Fortune 500 firm: $184 million (McKinsey, 2023)
- 9 adjustable risk sliders — Iran–Israel tension, Hormuz risk, freight rate, oil price, LPG index, port congestion, political stability, news sentiment, supplier concentration
- Animated risk gauge — arc visualization with real-time score (0–100)
- Severity levels — NORMAL / MINOR / MAJOR / SEVERE with colour-coded glow effects
- Top 4 risk drivers — animated contribution bars
- Financial impact estimate — USD millions at risk
- AI recommendations — 4 actionable steps generated by the model
- Hormuz closure probability — dedicated LPG supply threat index
- 8 live stat cards refreshing every 4 seconds — global risk, Hormuz risk, freight rate, oil price, LPG index, Red Sea alerts, active disruptions, vessels rerouted
- 30-day freight rate trend chart — Red Sea crisis spike visible
- Region risk heatmap — all 8 world regions with trend arrows ↑↓→
- 6 geopolitical event cards — active/inactive with weighted contribution scores
- Sector risk index — 8 sectors ranked by current disruption exposure
- Hand-crafted SVG world map — geographically accurate shapes including India peninsula, Sri Lanka, Arabian peninsula, Japan, Horn of Africa
- Pulsing animated hotspots — pulse speed reflects risk severity
- Click-to-predict — clicking any hotspot loads that region into Predict tab
- Risk colour coding — GREEN → YELLOW → ORANGE → RED
- Real elapsed timestamps — computed from actual
createdAtISO timestamps, updates every 10 seconds (no fake hardcoded strings) - Severity-coded alerts — CRITICAL / HIGH / MEDIUM / LOW
- 7 active global events — Hormuz naval exercises, Houthi strikes, TSMC, Mumbai port congestion
┌─────────────────────────────────────────────────────────────────────┐
│ CHAINGUARD AI — MODEL PIPELINE │
├─────────────────┬──────────────────┬────────────────────────────────┤
│ 📰 TEXT STREAM │ 📈 TIME SERIES │ 🕸️ GRAPH STREAM │
│ │ │ │
│ News headlines │ Freight rates │ Supplier–buyer network │
│ GDELT events │ Oil prices │ Tier-1 / Tier-2 / Tier-3 │
│ Conflict codes │ Trade volumes │ Import/export adjacency │
│ │ (past 90 days) │ │
│ ┌───────────┐ │ ┌────────────┐ │ ┌─────────────────────────┐ │
│ │ BERT / │ │ │ TFT + LSTM │ │ │ Graph Attention Net │ │
│ │ FinBERT │ │ │ │ │ │ (GAT) │ │
│ └─────┬─────┘ │ └─────┬──────┘ │ └───────────┬─────────────┘ │
│ 768-d embeds │ Temporal vecs │ Node embeddings │
└────────┼────────┴──────────┼───────┴───────────────┼───────────────┘
│ │ │
└───────────────────┼────────────────────────┘
▼
┌──────────────────────────────┐
│ Cross-Modal Attention │
│ (Fusion Layer) │
│ Dynamically weights which │
│ modality matters most now │
└──────────────┬───────────────┘
▼
┌───────────────────────────────────────┐
│ Multi-Task MLP Head │
│ ① Disruption probability (0–100%) │
│ ② Severity (Normal/Minor/Major/Sev) │
│ ③ Time to impact (days) │
└───────────────────────────────────────┘
PARALLEL:
┌──────────────────────────────┐
│ VAE — Anomaly Detector │
│ Unsupervised black-swan │
│ detection (no labels needed)│
└──────────────────────────────┘
| Model | Role | Why Chosen | Novel Contribution |
|---|---|---|---|
| BERT / FinBERT | News NLP encoder | Pre-trained on financial domain; captures geopolitical semantics | Fine-tuned on supply chain corpus |
| LSTM | Short-term time-series | Catches sudden spikes; fast training | Combined with TFT for multi-scale temporal |
| Temporal Fusion Transformer | Long-horizon forecasting | Multi-step prediction; interpretable attention | Primary time-series backbone |
| Graph Attention Network | Supplier network risk | Propagates risk through Tier-1/2/3 suppliers | First use for Tier-3 supply chain risk |
| Cross-Modal Attention | Fusion layer | Dynamically weights which modality is most predictive | Novel — no prior work in supply chain AI |
| Variational Autoencoder | Anomaly detection | Detects black-swan events without labelled data | Hormuz first-closure black-swan detection |
| Multi-Task MLP | Prediction head | Fast final classification + regression simultaneously | Joint severity + ETA output |
Iran–Israel Tension ████████████████████████ 22% ← Highest — Hormuz directly threatened
Freight Rate ██████████████████████ 20% ← Leading indicator, moves first
Hormuz Risk Score ████████████████████ 18% ← 21% world LPG transits daily
Oil Price █████████████ 12% ← Cascades into all sectors
LPG Price Index █████████ 8% ← Direct Hormuz commodity
Port Congestion ████████ 7% ← Operational bottleneck
Political Stability ███████ 6% ← Macro regional risk
News Sentiment █████ 4% ← NLP proxy (GDELT)
Supplier Concentration ████ 3% ← HHI single-source risk
| Technology | Version | Purpose |
|---|---|---|
| Python | 3.9+ | Core language |
| FastAPI | 0.111 | REST API framework |
| Uvicorn | 0.29 | ASGI server |
| Pydantic | 2.7 | Request/response validation |
| Technology | Version | Purpose |
|---|---|---|
| React | 18.2 | UI framework |
| Vite | 5.x | Build tool + dev server |
| Chart.js | 4.x | Trend line charts |
| Manrope | Google Fonts | Typography |
| Axios | 1.6 | HTTP client |
| SVG (custom) | — | World map — no external map library |
| Technology | Purpose |
|---|---|
| PyTorch | LSTM + VAE deep learning models |
| XGBoost | Baseline + feature importance |
| scikit-learn | Preprocessing + evaluation metrics |
| imbalanced-learn | SMOTE for class imbalance |
| HuggingFace Transformers | BERT / FinBERT architecture |
chainguard-ai/
│
├── 📂 backend/
│ ├── main.py ← FastAPI app — all routes + RiskModel class
│ └── requirements.txt ← Python dependencies
│
├── 📂 frontend/
│ ├── index.html ← Entry HTML
│ ├── vite.config.js ← Vite configuration
│ ├── package.json ← Node dependencies
│ └── src/
│ ├── main.jsx ← React entry point
│ └── App.jsx ← Full dashboard
│ ├── WorldMap() ← SVG world map with accurate continent paths
│ ├── RiskGauge() ← Animated arc gauge
│ ├── StatCard() ← Live metric cards
│ ├── AlertItem() ← Feed items with real elapsed timestamps
│ ├── TrendChart() ← Pure SVG line charts
│ ├── SectorBar() ← Sector risk bars
│ └── DriverBar() ← Risk driver contribution bars
│
├── 📂 notebooks/
│ └── Supply_Chain_Disruption_Prediction.ipynb
│
├── 📂 docs/
│ ├── Supply_Chain_Disruption_Prediction_Report.pdf
│ └── ChainGuard_AI_How_It_Works.pdf
│
└── README.md
python --version # Need 3.9+
node --version # Need 18+
npm --version # Need 8+git clone https://github.com/yourusername/chainguard-ai.git
cd chainguard-aicd backend
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # Mac / Linux
venv\Scripts\activate # Windows
# Install and run
pip install fastapi uvicorn pydantic
uvicorn main:app --reload --port 8000✅ Backend: http://localhost:8000
✅ Auto docs: http://localhost:8000/docs
cd frontend
npm install
npm run dev✅ Dashboard: http://localhost:3000
- Predict tab → Set Region =
Middle East / Hormuz, Sector =Energy / LPG - Drag Iran–Israel Tension to 8.5, Hormuz Risk to 7.5
- Click ⚡ RUN PREDICTION → watch gauge animate to SEVERE
- Dashboard tab → observe live metric cards updating every 4 seconds
- Map tab → click the Hormuz hotspot → auto-loads into Predict
Base URL: http://localhost:8000
| Method | Endpoint | Description | Refresh |
|---|---|---|---|
GET |
/health |
Server health check | — |
POST |
/predict |
Run AI risk prediction | On demand |
GET |
/global-risk |
Risk scores for all 8 regions | Every 30s |
GET |
/live-alerts |
Intelligence feed with real timestamps | On load |
GET |
/market-data |
Live market metrics with noise | Every 4s |
GET |
/trend-data |
30-day historical arrays | On load |
GET |
/sector-risk |
Sector risk scores + weekly trends | On load |
curl -X POST http://localhost:8000/predict \
-H "Content-Type: application/json" \
-d '{
"region": "Middle East / Hormuz",
"sector": "Energy / LPG",
"iran_tension": 8.5,
"hormuz_risk": 8.0,
"freight_rate": 3200,
"oil_price": 95.0,
"lpg_price": 72.0,
"port_congestion": 7.5,
"political_stability": 28.0,
"news_sentiment": -0.65,
"supplier_concentration": 0.7
}'Response:
{
"risk_score": 84.2,
"risk_level": "SEVERE",
"alert_code": "RED",
"color": "#EF4444",
"top_drivers": [
{ "name": "Iran–Israel Tension", "value": 18.7 },
{ "name": "Hormuz Risk Score", "value": 14.4 },
{ "name": "Freight Rate", "value": 10.7 },
{ "name": "Oil Price", "value": 7.6 }
],
"financial_impact_usd": 138000000,
"time_to_impact_days": 5,
"confidence": 93.1,
"recommendation": "IMMEDIATE: Activate contingency suppliers for Energy / LPG..."
}| # | Paper | Journal | Year |
|---|---|---|---|
| 1 | Hosseini et al. — Supply chain resilience quantification | Transportation Research Part E | 2019 |
| 2 | Cavalcante et al. — ML for resilient supplier selection | Decision Support Systems | 2019 |
| 3 | Nikolopoulos et al. — Forecasting during COVID-19 | European J. Operational Research | 2021 |
| 4 | Lim et al. — Temporal Fusion Transformer | Int. Journal of Forecasting | 2021 |
| 5 | Peng et al. — LSTM lead-time prediction in logistics | Computers & Industrial Engineering | 2022 |
| 6 | World Bank — Red Sea Crisis Economic Impact | World Bank Reports | 2024 |
| 7 | IMF — Middle East Conflict and Oil Market Volatility | IMF Publications | 2024 |
| Contribution | Why It's New |
|---|---|
| Geopolitical risk encoding (Iran–Israel index, CAMEO codes, UN sanctions) | No prior supply chain AI paper encoded live conflict escalation as model features |
| Cross-Modal Attention Fusion | No prior system dynamically weighted text vs. time-series vs. graph per crisis type |
| LPG / Hormuz sub-model | First dedicated AI module for Strait of Hormuz LPG vulnerability scoring |
| Tier-3 supplier GAT | Existing systems stop at Tier-1; this propagates risk to Tier-3 via graph attention |
| Hybrid VAE + Transformer | Unsupervised anomaly detection + supervised prediction in one unified system |
| Data | Source | Used For |
|---|---|---|
| Freight Rate Index | Freightos Baltic Index | Primary time-series feature (20%) |
| Oil Price (Brent Crude) | EIA.gov | Energy cascade feature (12%) |
| LPG Spot Price | Platts / ICIS | Hormuz commodity (8%) |
| Geopolitical Events | GDELT Project | News sentiment + conflict index |
| Supply Chain Labels | SCRN Dataset — Kaggle | Model training ground truth |
| Bilateral Trade Flows | UN Comtrade | Supplier network graph |
| Political Stability | World Bank Governance | Region base risk |
| Vessel Traffic (AIS) | MarineTraffic | Hormuz vessel count |
❌ "API OFFLINE" shown in header
Backend not running. Fix:
cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000❌ CORS error in browser console
Ensure backend is on port 8000. Check App.jsx line 3:
const API = "http://localhost:8000"❌ npm install fails
npm install --legacy-peer-deps❌ Port already in use
# Backend on different port
uvicorn main:app --reload --port 8001
# Update App.jsx line 3 → const API = "http://localhost:8001"
# Frontend on different port — edit vite.config.js:
server: { port: 3001 }❌ Python version error
python3 -m venv venv
python3 -m pip install fastapi uvicorn pydantic
uvicorn main:app --reload --port 8000Course : Artificial Intelligence & Deep Learning
Batch : AI & Data Science — 2025–27
Assignment : AI Solution Architecture
Framework : Research → Technology → Product → Venture
Topic : Supply Chain Disruption Prediction
| Section | Deliverable |
|---|---|
| Problem Definition | Iran–Israel / Red Sea crisis as real-world motivation |
| Literature Survey | 7 papers reviewed; gaps in geopolitical encoding identified |
| Dataset Exploration | GDELT, SCRN, UN Comtrade, Freightos FBX |
| AI Architecture | BERT + TFT + LSTM + GAT + VAE + Cross-Modal Attention |
| Prototype | This working full-stack application |
| Market Exploration | $28.9B market; Resilinc / Everstream competitor analysis |
| Entrepreneurial Potential | SaaS model; MVP → Series A roadmap |
MIT License — see LICENSE for details.
Built for AI & Data Science Batch 2025–27 ⛓️
⭐ Star this repo if you found it useful!