Syn3rgy — Global Supply Chain Intelligence Platform

A real-time supply chain risk command center built on Next.js 14 (App Router) with a 3D globe, AI-powered cascade analysis, live geopolitical news intel, and AIS vessel tracking.

---

Features

Module	Description
Command Center	3D Mapbox globe with DeckGL overlays — supply chain nodes, trade arcs, threat layers, AIS vessels, and deployed mitigation markers
War Room Simulator	Scenario threat simulator — historical + live NewsData.io events, cascade analysis, impact analysis, risk matrix heatmap, mitigation deployment
Risk Explorer	Filterable risk feed from /api/risks with severity-gated cards
Risk Radar	Animated polar radar of active threat categories
Settings	Full system configuration UI — alert thresholds, API integration tests, map defaults, HSN normalization, persistence via settings.json

---

Getting Started

Prerequisites

• Node.js 18+
• A .env.local file in djapp/ with the following keys:

NEXT_PUBLIC_MAPBOX_TOKEN=pk.eyJ1...
NVIDIA_API_KEY=nvapi-...
NEWSDATA_IO_API=pub_...
NEXT_PUBLIC_AISSTREAM_API_KEY=...

Run the frontend

cd djapp
npm install
npm run dev

Open http://localhost:3000.

Run the Python backend (optional)

cd server
pip install -r requirements.txt
python app.py

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Browser (Next.js 14)                     │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ /command     │  │ /simulator   │  │ /settings          │   │
│  │ CommandCenter│  │ WarRoom      │  │ System Config      │   │
│  │              │  │              │  │                    │   │
│  │ SupplyChain  │  │ Cascade tab  │  │ Alert Triggers     │   │
│  │ Map (DeckGL) │  │ Impact tab   │  │ API Integrations   │   │
│  │ RiskRadar    │  │ Risk Matrix  │  │ Map & Display      │   │
│  │ KPIDashboard │  │ Mitigations  │  │ HSN Normalization  │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬───────────┘   │
│         │                 │                    │               │
│  ┌──────▼─────────────────▼────────────────────▼───────────┐  │
│  │                  Next.js API Routes                      │  │
│  │                                                          │  │
│  │  GET/POST /api/settings          ← settings.json file   │  │
│  │  POST /api/settings/test-connection  ← live ping tests  │  │
│  │  POST /api/settings/normalize-hsn    ← HSN pipeline     │  │
│  │  GET  /api/risks                 ← NVIDIA LLM           │  │
│  │  GET  /api/region-news           ← NewsData.io          │  │
│  │  GET  /api/geocode               ← Mapbox Geocoding     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │               Client-side services                       │  │
│  │                                                          │  │
│  │  useAISStream  WebSocket → aisstream.io                  │  │
│  │  localStorage  syn3rgy_settings  (settings cache)        │  │
│  │  Mapbox GL JS  globe projection + native Marker/Popup    │  │
│  │  DeckGL        ScatterplotLayer, ArcLayer, PathLayer,    │  │
│  │                TextLayer (interleaved with Mapbox GL)    │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                   External Services                             │
│                                                                 │
│  NVIDIA NIM API   meta/llama-3.3-70b-instruct                  │
│  NewsData.io      Live global news articles                     │
│  AISStream.io     Real-time vessel positions (WebSocket)        │
│  Mapbox           3D globe tiles + geocoding API                │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                   Python Backend (server/)                      │
│                                                                 │
│  app.py           Flask REST API                                │
│  db.py            Database layer                                │
│  fetchers.py      External data fetchers                        │
│  graph_db.py      Graph database integration                    │
└─────────────────────────────────────────────────────────────────┘

Key data flows

Risk feed — /api/risks calls NVIDIA NIM with a structured prompt; responses are severity-filtered (via minSeverityThreshold from settings) and rendered on the RiskRadar and node overlays.

Globe markers — Deployed mitigation nodes from the War Room Simulator are passed as deployedNodeIds to SupplyChainMap. Two DeckGL ScatterplotLayers (glow + ring) mark the crisis zone. Native mapboxgl.Marker elements with occludedOpacity are placed at each node for 3D globe-aware annotation with interactive popups.

Settings persistence — Settings are written to settings.json server-side on every save. The browser caches them in localStorage['syn3rgy_settings']. All pages read from localStorage on mount; /api/settings is the source of truth.

HSN normalization — POST /api/settings/normalize-hsn reads settings.json, then runs each raw code through: alias substitution → strip spaces/dots → case transform → digit truncation → zero-pad to target WCO precision (2/4/6/8-digit).

---

Project Structure

djapp/
├── src/
│   ├── app/
│   │   ├── page.tsx                  # Root redirect
│   │   ├── layout.tsx                # Root layout + fonts
│   │   ├── globals.css               # Tailwind + custom tokens + keyframes
│   │   ├── command/page.tsx          # Command Center (main view)
│   │   ├── simulator/page.tsx        # War Room Simulator
│   │   ├── explorer/page.tsx         # Risk Explorer
│   │   ├── risk/page.tsx             # Risk detail
│   │   ├── settings/page.tsx         # System Configuration
│   │   └── api/
│   │       ├── risks/route.ts        # NVIDIA LLM risk generation
│   │       ├── region-news/route.ts  # NewsData.io proxy
│   │       ├── geocode/route.ts      # Mapbox geocoding proxy
│   │       └── settings/
│   │           ├── route.ts          # GET/POST settings (settings.json)
│   │           ├── test-connection/  # Live API connectivity tests
│   │           └── normalize-hsn/   # HSN code normalization pipeline
│   ├── components/
│   │   ├── SupplyChainMap.tsx        # DeckGL + Mapbox 3D globe
│   │   ├── DashboardLayout.tsx       # Shell with SideNavBar + TopNavBar
│   │   ├── SideNavBar.tsx            # Left navigation
│   │   ├── TopNavBar.tsx             # Top bar
│   │   ├── RiskRadar.tsx             # Polar radar chart
│   │   └── KPIDashboard.tsx          # KPI metric strip
│   ├── hooks/
│   │   └── useAISStream.ts           # AISStream WebSocket hook
│   └── data/
│       ├── supplyChain.json          # Static node/edge graph
│       ├── threatLayers.json         # Threat overlay data
│       └── tradeRoutes.json          # Trade route paths
├── settings.json                     # Persisted runtime config (git-ignored)
├── .env.local                        # API keys (git-ignored)
├── next.config.ts
└── tsconfig.json

server/
├── app.py
├── db.py
├── fetchers.py
├── graph_db.py
└── requirements.txt

---

Environment Variables

Variable	Required	Description
NEXT_PUBLIC_MAPBOX_TOKEN	Yes	Mapbox GL JS public token
NVIDIA_API_KEY	Yes	NVIDIA NIM API key for LLM inference
NEWSDATA_IO_API	Yes	NewsData.io API key
NEXT_PUBLIC_AISSTREAM_API_KEY	Yes	AISStream WebSocket API key

---

Tech Stack

Layer	Technology
Framework	Next.js 14 — App Router, TypeScript
Styling	Tailwind CSS with Material Design 3 custom tokens
3D Globe	Mapbox GL JS — globe projection, native Marker/Popup, fog
Map overlays	deck.gl — ScatterplotLayer, ArcLayer, PathLayer, TextLayer
AI inference	NVIDIA NIM — meta/llama-3.3-70b-instruct
News intel	NewsData.io REST API
Vessel tracking	AISStream.io WebSocket
Fonts	Space Grotesk · JetBrains Mono · Inter