See the disruption before it sees you.
Quick start · The tour · How it thinks · Scenario catalog · Extend it
The Command Center at rest — a live world, animated energy corridors, India's reserves, and a one-line situation ribbon. Nothing else until you ask.
India imports ~88% of its crude oil. 40–45% of it transits a single strait — Hormuz. The strategic reserve covers ~9.5 days. When something breaks out there, the response window is measured in hours, and the tools most teams have were built for predictable weather.
VOYANT is the missing layer: a platform that continuously watches risk signals, simulates any disruption — predefined or typed in plain English — as a multi-step cascade across the global trade graph, and turns it into procurement actions, reserve decisions, and an executive brief you could hand to a minister.
Every interaction answers the same six questions, in order, with evidence:
What is happening? · Why? · What happens next? · What are the consequences? · What should we do? · How confident are we?
The Scenario Library: 18 crises across six world regions and five disruption types, grouped by severity, each card carrying risk level, region, duration, industries, and difficulty. And the composer at the top takes plain English — type "China blockades the Taiwan Strait for a month" and VOYANT parses the trigger, the epicenter, the intensity, and the horizon, then runs the exact same pipeline as any built-in scenario.
What happens when you hit Run
- The description is parsed deterministically — trigger keywords, chokepoint/country recognition, intensity and horizon extraction (an LLM refines the parse when a key is present, never replacing the deterministic floor).
- The parsed blueprint is registered server-side, so every surface — War Room, Time Machine, narrative — treats your custom scenario like a first-class citizen.
- The full six-agent pipeline runs. Milliseconds later the map, the cascade, the brief, procurement, and reserves have all changed.
This is the platform's signature: not one number, but the chain. A Hormuz closure becomes shipping disruption → export reduction → insurance spike → supplier competition → freight costs → procurement rerouting → reserve activation → inflationary pressure — each step with its own magnitude, narrative, and confidence. And on the map, every downstream-exposed country is shaded by how hard the cascade hits it, computed from the world trade graph in both directions: who imports from the disrupted exporters, and who those exporters sell to.
The Executive Brief: eight sections — situation, current risks, key drivers, supply-chain impact, economic impact, procurement, reserves, priority actions — every sentence computed from the actual pipeline artifacts, plus a rendered markdown report. Alongside it in the drawer: ranked procurement actions (with expected risk reduction, cost delta, confidence, and constraints), per-site reserve decisions with the national days-of-cover countdown, the affected-countries list, and the Opportunity Radar — the upside view of the same picture.
Real decisions come from an argument, not an oracle. Six specialist advisors — geopolitical analyst, energy economist, logistics & shipping analyst, procurement advisor, strategic reserve advisor, economic risk analyst — deliver positions, challenge each other with rebuttals grounded in the computed numbers, and get synthesized by a chairperson into a ruling with numbered directives.
Observer controls
| Control | What it does |
|---|---|
| Space / Pause | Freeze and resume the discussion |
| 1× / 2× / 4× | Playback speed |
| Jump to verdict | Skip straight to the chairperson's ruling |
| Advisor icons | Filter the feed to the voices you want |
| View evidence | Expand each statement's numeric citations |
| Export summary | Download the entire debate as markdown |
The Crisis Time Machine replays the scenario day by day — pre-crisis, onset, peak, de-escalation, recovery — while the map recolors, routes flip status, the risk index climbs, and the SPR countdown drains in front of you. Drag the scrubber or press play.
Every sovereign country is live. Click one and its intelligence card appears — risk score, energy posture, alliances, trading partners, key imports and exports, strategic commodities — while the trade-relations overlay draws its links to leading partners. Pin a country to compare it side-by-side with any other. ~170 states carry structured profiles; none of them are "inactive."
Press / or Ctrl+K anywhere. Run any scenario, open any panel, toggle any layer, convene the War Room, reset the camera, or fly to any country, corridor, port, supplier, or reserve on the planet.
| Shortcut | Action |
|---|---|
| / or Ctrl+K | Command palette |
| ↑ ↓ ↵ | Navigate & run palette results |
| Esc | Dismiss any overlay |
| Space | Pause / resume the War Room |
| Double-click map | Zoom in |
Three commitments shape everything:
1 · Deterministic core. Risk, cascade, procurement, reserve, and brief numbers come from typed engines. Same inputs → same answers, always, with a full execution trace.
2 · LLMs enhance, never decide. Claude narrates the brief, voices the War Room, classifies live headlines, refines scenario parsing — every call schema-validated, every surface with a deterministic fallback. The platform is fully functional with zero model access.
3 · The map is the product. ~90% of the viewport, permanently. Everything else is summoned, used, and dismissed.
flowchart LR
subgraph IN[" Inputs"]
BP["Scenario blueprint<br/><i>library · structured · natural language</i>"]
DS["Hybrid data source<br/><i>curated + live GDELT + world registry</i>"]
end
subgraph AGENTS[" Six agents, in sequence — every step traced"]
A1["Geopolitical<br/>Signal"] -->|signals| A2["Knowledge<br/>Graph"]
A2 -->|graph| A3["Scenario<br/>Modeling"]
A3 -->|"cascade + impacts"| A4["Procurement<br/>Orchestrator"]
A4 -->|actions| A5["Strategic<br/>Reserve"]
A5 -->|decisions| A6["Executive<br/>Brief"]
end
OUT[" Intelligence Response<br/><i>brief · actions · reserves · cascade ·<br/>exposed countries · risk scores · trace</i>"]
BP --> AGENTS
DS --> AGENTS
A6 --> OUT
OUT --> UI[" Command Center"]
LLM[" LLM enhancement layer — optional, validated, deterministic fallback"] -.-> A1
LLM -.-> A3
LLM -.-> A6
Warm end-to-end latency: ~1–2 ms, shown live in the header.
Scenarios aren't lookup tables. A blueprint (trigger + epicenter + intensity) propagates through a typed chain, each effect derived from the one before it:
flowchart LR
T[" Trigger<br/><i>e.g. Hormuz closes</i>"] --> S1["Shipping<br/>disruption"]
S1 --> S2["Export<br/>reduction"] --> S3["Insurance<br/>premiums"] --> S4["Supplier<br/>competition"]
S4 --> S5["Freight<br/>costs"] --> S6["Procurement<br/>rerouting"] --> S7["Reserve<br/>activation"] --> S8["Inflationary<br/>pressure"]
S1 -.-> X[" Downstream exposure<br/><i>trade-graph propagation,<br/>both directions</i>"]
The chains and blueprints are configuration, not code — the domain knowledge lives in cascade-templates.ts and scenario frontmatter. Eleven trigger kinds cover geopolitical, logistics, infrastructure, climate, and economic disruption.
The six agents, up close
Each agent implements the same typed contract — analyze → reason → generateOutput → getConfidenceScore — and delegates all computation to a deterministic engine. Agents orchestrate and explain; engines decide.
| Agent | Backed by | Produces |
|---|---|---|
| Geopolitical Signal | Curated + live GDELT ingestion | Structured, evidence-linked risk signals |
| Knowledge Graph | Graph build + BFS traversal | Country–supplier–route–refinery topology, chokepoint exposure |
| Scenario Modeling | The cascade engine | Multi-step chain, exposed countries, per-commodity impacts |
| Procurement Orchestrator | Reliability/lead-time/premium scoring | Ranked, explainable sourcing actions |
| Strategic Reserve | Drawdown projection + decision matrix | Hold / release / partial / swap / replenish per site |
| Executive Brief | Section synthesizer | The eight-section brief + markdown report |
The Map Engine (for the systems-minded)
The geospatial layer is a framework-independent engine that owns the MapLibre instance — React only dispatches commands and subscribes to two facts (ready, hover).
- Strict staged init: create →
style.load→idle→ camera constraints → sources → layers → interactions → ready. No timeouts, no races. - GPU-side interaction: hover and selection are pure feature-state; pointer movement causes zero React renders of the map shell.
- One rAF loop animates the corridors, scales flow speed to scenario intensity, and suspends itself on hidden tabs and software renderers.
- Pluggable layers: countries, risk weather, corridors (with direction chevrons), ports, refineries, suppliers, reserves, risk events, trade relations, cascade impact — adding one is a single registry entry.
- Cinematic camera: 45° resting pitch, one easing vocabulary for fly/ease/fit/focus/zoom.
Full write-up: docs/map-engine.md
18 scenarios · 6 regions · 5 disruption types · every one runs the full pipeline and passes verification.
| Scenario | Region | Type | Risk | |
|---|---|---|---|---|
| 🔴 | Hormuz Closure | Middle East → South Asia | Chokepoint | severe |
| 🔴 | Taiwan Strait Blockade | East Asia | Conflict | severe |
| 🟠 | Red Sea Disruption | Red Sea / Suez | Shipping lane | high |
| 🟠 | Supplier Sanctions | Gulf → South Asia | Sanctions | high |
| 🟠 | Iran Sanctions Escalation | Persian Gulf | Sanctions | high |
| 🟠 | Pipeline Attack | Saudi Arabia | Supplier outage | high |
| 🟠 | Malacca Strait Disruption | Southeast Asia | Shipping lane | high |
| 🟠 | Russian Gas Cutoff | Europe | Pipeline | high |
| 🟠 | Baltic Pipeline Sabotage | Northern Europe | Infrastructure | high |
| 🟠 | Niger Delta Unrest | West Africa | Supplier outage | high |
| 🟠 | US Gulf Hurricane | North America | Climate | high |
| 🟠 | Products Pipeline Cyberattack | US East Coast | Cyber | high |
| 🟠 | Venezuela Sanctions Snapback | South America | Sanctions | high |
| 🟠 | Supplier Bankruptcy | Atlantic Basin | Counterparty | high |
| 🟡 | OPEC Production Cut | Gulf / Global | Economic | moderate |
| 🟡 | Major Port Closure | West Coast India | Port | moderate |
| 🟡 | Panama Canal Drought | Central America | Climate | moderate |
| 🟡 | Global Demand Spike | Global | Economic | moderate |
…and the 19th, 20th, 21st are whatever you type into the composer.
git clone <this-repo>
cd Voyant
npm install
npm run dev # → http://localhost:3000 (or: npx next dev -p 4000)That's it — no keys, no database. The deterministic platform is fully functional offline.
Optional environment:
| Variable | Effect |
|---|---|
OPENROUTER_API_KEY |
Unlocks the AI narrative, War Room voicing, live-signal classification, and NL-parse refinement (Claude via OpenRouter) |
GEMINI_API_KEY |
Alternative model provider |
VOYANT_LIVE_SIGNALS=off |
Disables live GDELT news ingestion |
| Command | What it proves |
|---|---|
npm run typecheck |
Strict TypeScript, zero errors |
npm test |
48 unit + pipeline tests |
npm run verify:scenarios |
All 18 scenarios end-to-end — asserts multi-step cascade reasoning and downstream propagation, writes the report |
npm run eval |
Evaluation harness with timestamped logs |
npm run build |
Production build (stop the dev server first) |
Add a scenario — zero code
Drop a markdown file in scenarios/:
---
id: scenario-my-crisis
name: My Crisis
type: multi_region_conflict
regions: east_asia
commodities: crude_oil, lng
windowStart: 2026-09-01
windowEnd: 2026-10-01
triggerKind: conflict_escalation # ← cascade blueprint
intensity: 0.9
epicenterChokepoints: Taiwan Strait
epicenterCountries: CN, TW
riskLevel: severe # ← browser card
regionLabel: East Asia
duration: 30 days
industries: Shipping, LNG
difficulty: expert
summary: One line for the card.
---
# My Crisis
## Background … Trigger … Timeline … Executive SummaryIt appears in the library, the palette, the Time Machine, and verify:scenarios — no application logic touched.
Add or enrich a country — one line
In src/data/world/country-registry.ts:
c("BR", "BRA", "Brazil", "latin_america", {
alliances: ["BRICS", "OPEC+"],
tradingPartners: ["CN", "US", "AR"],
majorExports: ["crude oil", "iron ore", "soybeans"],
strategicCommodities: ["crude_oil"],
energyDependence: "net_exporter",
riskBaseline: 26,
}),Geometry joins automatically by ISO3; centroids are computed from the polygons. Search, selection, relations, and cascade exposure pick it up with no further wiring.
Add a War Room advisor
- Extend
WarRoomParticipantIdinsrc/types/war-room.ts. - Add the position in
war-room-engine.ts— stance, argument, and rebuttal must be built from the pipeline's computed numbers. - Give the seat an icon in the overlay's
SEAT_META.
Add a map layer
- Add the id to
LayerIdand one entry inlayer-registry.ts. - If it needs new data: one collection builder in
geojson-manager.ts. - One
VoyantLayerDefinitioninlayer-manager.ts.
Toggles, palette commands, hover, and selection wire themselves.
Project structure
scenarios/ 18 crisis scenarios (markdown + blueprint frontmatter)
scripts/ verify-scenarios.ts — the validation runner
docs/ Architecture docs, reports, screenshots
src/
├─ app/ Next.js shell + 13 typed API routes
├─ types/ The contract layer — every domain type
├─ data/
│ ├─ mock/ Curated India / Middle East dataset
│ └─ world/ Country registry (~170 states) + chokepoint registry
├─ lib/
│ ├─ agents/ The six intelligence agents
│ ├─ ai/ Model routers + safe LLM utilities (tryCompleteJson)
│ ├─ scenario/ Cascade engine: templates, blueprints, NL parser
│ ├─ scenarios/ Library loader + ad-hoc registry
│ ├─ risk|procurement|reserves|brief/ Deterministic engines
│ ├─ knowledge-graph/ Graph build + traversal
│ ├─ signals/ Live GDELT ingestion (non-blocking)
│ ├─ time-machine/ Crisis frame generator
│ ├─ war-room/ Six-advisor debate engine
│ └─ orchestrator/ Pipeline orchestration + execution trace
├─ geospatial/
│ ├─ engine/ THE MAP ENGINE — camera, layers, geojson, interaction
│ └─ components|hooks|state|config|utils/
└─ command-center/ Chrome: top bar, rail, drawers, palette, overlays
| Doc | Contents |
|---|---|
| Scenario Intelligence Engine | Cascade reasoning, NL parsing, config-driven scenarios |
| Global Intelligence | World registry, relations overlay, War Room workflow |
| Map Engine | Geospatial architecture + upstream workarounds |
| Verification Report | Generated — every scenario's cascade chain & exposure |
| Performance Report | Measured rendering + pipeline numbers |
| UX Audit | Design decisions and honest open debts |
| docs/README.md | Full index, including the Phase-1 design docs |
Next: live AIS vessel tracking as a pluggable layer · database-backed data source behind the existing accessor · multi-round War Room debates · presentation deck + demo video.
Known limits: the dataset is demo-grade curated approximation (deep on the India–Gulf corridor, baseline everywhere else — swap in licensed data behind the same interface for production) · live ingestion is headline-level, not vessel-level · ad-hoc scenarios live in server memory per process · microstates without polygons in the 1:110m geometry are searchable but not clickable · LLM surfaces silently step aside without a funded key, by design.
Built for the ET AI Hackathon 2026 · Next.js 15 · React 19 · TypeScript strict · MapLibre GL · Zod · Zustand · Vitest
VOYANT — turn a reactive crisis into a managed, anticipatory process.