Who it is for
- Supply-chain and commodity desks stress-testing routing assumptions against a named event.
- Risk and policy teams translating a geopolitical or environmental scenario into concrete country exposure.
- Leadership building talking-tracks around “if X happens, what breaks first?”
Opening the engine
Scenario Engine lives inside the Supply Chain panel on the main dashboard. Each pre-built scenario template renders as a trigger button; clicking a scenario starts an async job and activates the visual overlay once results land. You can also drive it programmatically — see Scenarios API for the/templates, /run, and /status endpoints.
Scenario templates
Templates are defined inserver/worldmonitor/supply-chain/v1/scenario-templates.ts. Each template has a type drawn from a small, curated set so scenarios are browsable by category rather than a free-form list.
The currently shipped types are:
| Type | What it models |
|---|---|
conflict | Chokepoint closure or degradation driven by an active conflict event (Taiwan Strait full closure, Suez + Bab-el-Mandeb simultaneous, Hormuz tanker blockade). |
weather | Climatic disruption — e.g. the Panama Canal 50% drought scenario. |
sanctions | Targeted trade restrictions (e.g. Russia / Baltic grain suspension). |
tariff_shock | A sudden tariff action and its cost pass-through (e.g. US tariff escalation on electronics). |
affectedHs2: [] means all HS2 chapters (the registry stores that sentinel as null). Run templates as-is — there are no sliders in v1. The ScenarioType union leaves room for infrastructure and pandemic categories, but no templates of those types ship today.
What you get back
A completed scenario returns:- Affected chokepoints — which ones go red on the map.
- Impact ranking — the top affected seeded reporter countries by ISO-2, ordered by the worker’s relative weighted impact score.
totalImpactis not a currency amount. - Template echo — the worker-derived template key (
affectedChokepointIds.join('+'), ortariff_shockwhen there are no physical chokepoints), duration, disruption percent, and cost-shock multiplier so clients can render the run without re-looking up the catalog. The status result does not repeataffectedHs2; read sector scope from/list-scenario-templates. - A summary card injected into the Supply Chain panel that stays visible until you deactivate the scenario.
scenarioState on every map renderer (deck.gl, globe, SVG fallback) so chokepoint colors and country choropleths reflect the disruption until you deactivate. This is coordinated by MapContainer.activateScenario at src/components/MapContainer.ts:1010, which is explicitly PRO-gated.
Tier & gating
Scenario Engine is PRO. Free users see the trigger buttons but are blocked at activation: ascenario-engine gate-hit event is logged and the map is not repainted. The ScenarioService.RunScenario handler also enforces PRO at the edge (server/worldmonitor/scenario/v1/run-scenario.ts).
Rate limits on the API side — 10 jobs / minute / IP, with queue backpressure once the pending queue is already above 100 jobs — are documented in Scenarios API.
Run it yourself
The workflow is inherently async — the edge function enqueues a job, a Railway worker computes the impact, and the result is polled back:- Open the Supply Chain panel.
- Click a scenario trigger button (the template name).
- The button disables while the job runs (typically 5-30 s).
- When the result lands, the map repaints, and a scenario banner is prepended to the panel. The banner always shows: a ⚠ icon, the scenario name, the top 5 impacted countries with per-country impact %, and a × dismiss control. When the scenario’s result payload includes template parameters (duration, disruption %, cost-shock multiplier), the banner additionally renders a chip row (e.g.
14d · +110% cost) and a tagline line such as “Simulating 14d / 100% closure / +110% cost on 1 chokepoint. Chokepoint card below shows projected score; map highlights disrupted routes.” The affected chokepoints themselves are highlighted on the map and on the chokepoint cards rather than listed by name in the banner. - Click the × dismiss control on the banner (aria-label: “Dismiss scenario”) to clear the scenario state — the map repaints to its baseline and the panel re-renders without the projected score and red-border callouts.
POST /api/scenario/v1/run-scenario — enqueue, then poll GET /api/scenario/v1/get-scenario-status until the response has a terminal status ("done" on success, "failed" on error). Non-terminal states are "pending" (queued) and "processing" (worker started); both can persist for several seconds. See the status lifecycle table for the full contract.
Data behind Scenario Engine
- Scenario templates —
server/worldmonitor/supply-chain/v1/scenario-templates.ts. Additions require a proto-side change; not user-configurable today. - Job queue — Redis list
scenario-queue:pending; worker results land atscenario-result:{jobId}. - Chokepoint registry — the same registry that backs live chokepoint status and Route Explorer, ensuring scenario results visually align with the rest of the product.
- Trade / impact data — HS2 exposure cache entries read from
supply-chain:exposure:{ISO2}:{HS2}:v1. Ifiso2is omitted, v1 computes only the seeded reporter set:US,CN,RU,IR,IN, andTW. Supplyingiso2scopes the job to that single country key.
Impact Math
For physical chokepoint scenarios, each matching exposure entry contributes:vulnerabilityIndex as the exposure proxy:
adjustedImpact by country, sorts descending, and returns the
top 20. impactPct is a 0-100 share against a denominator floor of 1, so the top returned country can be below 100 when every returned totalImpact is below 1:
Related workflows
- Route Explorer — run a specific lane against today’s state.
- Scenarios API — the underlying HTTP contract.
- Supply Chain — the broader service that backs the Supply Chain panel.