mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
d1a4cf7780
* docs(mintlify): add Route Explorer + Scenario Engine workflow pages Checkpoint for review on the IA refresh (per plan docs/plans/2026-04-19-001-feat-docs-user-facing-ia-refresh-plan.md). - docs/docs.json: link Country Resilience Index methodology under Intelligence & Analysis so the flagship 222-country feature is reachable from the main nav (previously orphaned). Add a new Workflows group containing route-explorer and scenario-engine. - docs/route-explorer.mdx: standalone workflow page. Who it is for, Cmd+K entry, four tabs (Current / Alternatives / Land / Impact), inputs, keyboard bindings, map-state integration, PRO gating with free-tier blur + public-route highlight, data sources. - docs/scenario-engine.mdx: standalone workflow page. Template categories (conflict / weather / sanctions / tariff_shock / infrastructure / pandemic), how a scenario activates on the map, PRO gating, pointers to the async job API. Deferred to follow-up commits in the same PR: - documentation.mdx landing rewrite - features.mdx refresh - maritime-intelligence.mdx link-out to Route Explorer - Panels nav group (waits for PR 2 content) All content grounded in live source files cited inline. * docs(mintlify): fix Route Explorer + Scenario Engine review findings Reviewer caught 4 cases where I described behavior I hadn't read carefully. All fixes cross-checked against source. - route-explorer (free-tier): the workflow does NOT blur a numeric payload behind a public demo route. On free tier, fetchLane() short-circuits to renderFreeGate() which blurs the left rail, replaces the tab area with an Upgrade-to-PRO card, and applies a generic public-route highlight on the map. No lane data is rendered in any tab. See src/components/RouteExplorer/ RouteExplorer.ts:212 + :342. - route-explorer (keyboard): Tab / Shift+Tab moves focus between the panel and the map. Direct field jumps are F (From), T (To), P (Product/HS2), not Tab-cycling. Also added the full KeyboardHelp binding list (S swap, ↑/↓ list nav, Enter commit, Cmd+, copy URL, Esc close, ? help, 1-4 tabs). See src/components/RouteExplorer/ KeyboardHelp.ts:9 and RouteExplorer.ts:623. - scenario-engine: the SCENARIO_TEMPLATES array only ships templates of 4 types today (conflict, weather, sanctions, tariff_shock). The ScenarioType union includes infrastructure and pandemic but no templates of those types ship. Dropped them from the shipped table and noted the type union leaves room for future additions. - scenario-engine + api-scenarios: the worker writes status: 'done' (not 'completed') on success, 'failed' on error; pending is synthesised by the status endpoint when no worker record exists. Fixed both the new workflow page and the merged api-scenarios.mdx completed-response example + polling language. See scripts/scenario-worker.mjs:421 and src/components/SupplyChainPanel.ts:870. * docs(mintlify): fix third-round review findings (real IDs + 4-state lifecycle) - api-scenarios (template example): replaced invented hormuz-closure-30d / ["hormuz"] with the actually-shipped hormuz-tanker-blockade / ["hormuz_strait"] from scenario- templates.ts:80. Listed the other 5 shipped template IDs so scripted users aren't dependent on a single example. - api-scenarios (status lifecycle): worker writes FOUR states, not three. Added the intermediate "processing" state with startedAt, written by the worker at job pickup (scenario- worker.mjs:411). Lifecycle now: pending → processing → done|failed. Both pending and processing are non-terminal. - scenario-engine (scripted use blurb): mirror the 4-state language and link into the lifecycle table. - scenario-engine (UI dismiss): replaced "Click Deactivate" with the actual × dismiss control on the scenario banner (aria-label: "Dismiss scenario") per src/components/SupplyChainPanel.ts:790. Also described the banner contents (name, chokepoints, countries, tagline). - api-shipping-v2: while fixing chokepoint IDs, also corrected "hormuz" → "hormuz_strait" and "bab-el-mandeb" → "bab_el_mandeb" across all four occurrences in the shipping v2 page (from PR #3209). Real IDs come from server/_shared/chokepoint- registry.ts (snake_case, not kebab-case, not bare "hormuz"). * docs(mintlify): fix fourth-round findings (banner DOM, webhook TTL refresh) - scenario-engine: accurate description of the rendered scenario banner. Always-present elements are the ⚠ icon, scenario name, top-5 impacted countries with impact %, and dismiss ×. Params chip (e.g. '14d · +110% cost') and 'Simulating …' tagline are conditional on the worker result carrying template parameters (durationDays, disruptionPct, costShockMultiplier). The banner never lists affected chokepoints by name — the map and the chokepoint cards surface those. Per renderScenarioBanner at src/components/SupplyChainPanel.ts:750. - api-shipping-v2 (webhook TTL): register extends both the record and the owner-index set's 30-day TTL via atomic pipeline (SET + SADD + EXPIRE). rotate-secret and reactivate only extend the record's TTL — neither touches the owner-index set, so the owner index can expire independently if a caller only rotates/reactivates within a 30-day window. Re-register to keep both alive. Per api/v2/shipping/webhooks.ts:230 (register pipeline) and :325 (rotate setCachedJson on record only). * docs(mintlify): fix PRO auth contract (trusted origin ≠ PRO) - api-scenarios: 'X-WorldMonitor-Key (or trusted browser origin) + PRO' was wrong — isCallerPremium() explicitly skips trusted-origin short-circuits (keyCheck.required === false) and only counts (a) an env-valid or user-owned wm_-prefixed API key with apiAccess entitlement, or (b) a Clerk bearer with role=pro or Dodo tier ≥ 1. Browser calls work because premiumFetch() injects one of those credentials per request, not because Origin alone authenticates. Per server/_shared/premium-check.ts:34 and src/services/premium-fetch.ts:66. - usage-auth: strengthened the 'Entitlement / tier gating' section to state outright that authentication and PRO entitlement are orthogonal, and that trusted Origin is NOT accepted as PRO even though it is accepted for public endpoints. Listed the two real credential forms that pass the gate. * docs(mintlify): fix stale line cite (MapContainer.activateScenario at :1010) Greptile review P2: prose cited MapContainer.ts:1004 but activateScenario is declared at :1010. Line 1004 landed inside the JSDoc block. * docs(mintlify): finish PR 1 — landing rewrite, features refresh, maritime link-out Completes the PR 1 items from docs/plans/2026-04-19-001-feat-docs-user- facing-ia-refresh-plan.md that were deferred after the checkpoint on Route Explorer + Scenario Engine + CRI nav. No new pages — only edits to existing pages to point at and cohere with the new workflow pages. - documentation.mdx: landing rewrite. Dropped brittle counts (344 news sources, 49 layers, 24 CII countries, 31+ sources, 24 typed services) in favor of durable product framing. Surfaced the shipped differentiators that were invisible on the landing previously: Country Resilience Index (222 countries, linked to its methodology page), AI daily brief, Route Explorer, Scenario Engine, MCP server. Kept CII and CRI as two distinct country-risk surfaces — do not conflate. - features.mdx: replaced the 'all 55 panels' Cmd+K claim and the stale inventory list with family-grouped descriptions that include the panels this audit surfaced as missing (disease- outbreaks, radiation-watch, thermal-escalation, consumer-prices, latest-brief, forecast, country-resilience). Added a Workflows section linking to Route Explorer and Scenario Engine, and a Country-level risk section linking CII + CRI. Untouched sections (map, marker clustering, data layers, export, monitors, activity tracking) left as-is. - maritime-intelligence.mdx: collapsed the embedded Route Explorer subsection to a one-paragraph pointer at /route-explorer so the standalone page is the canonical home. Panels nav group remains intentionally unadded; it waits on PR 2 content to avoid rendering an empty group in Mintlify.
100 lines
5.8 KiB
Plaintext
100 lines
5.8 KiB
Plaintext
---
|
||
title: "Route Explorer"
|
||
description: "Plan a shipment between any two countries and see the chokepoints, bypass options, and country-level impact on a full-screen, keyboard-first map workflow."
|
||
---
|
||
|
||
Route Explorer is a full-screen workflow for reasoning about how a specific shipment moves through the world: which maritime chokepoints it crosses, what alternative routes exist, what land corridors could substitute, and which countries take the brunt of the disruption if a chokepoint closes. It is the fastest way to ask "if this lane is disrupted, what actually happens?"
|
||
|
||
## Who it is for
|
||
|
||
- **Shippers, traders, and freight desks** evaluating lane risk for a specific origin-destination-commodity combination.
|
||
- **Analysts** comparing baseline routing to plausible detours under disruption.
|
||
- **Policy and risk teams** looking at country-level import dependency and exposure.
|
||
|
||
## Opening Route Explorer
|
||
|
||
- **Cmd / Ctrl + K → "Route Explorer — plan a shipment"** (`src/config/commands.ts:254`).
|
||
- Or use the dedicated action in the command palette; the workflow opens as a full-screen modal over the map.
|
||
|
||
Route state is encoded in the URL (`src/components/RouteExplorer/url-state.ts`), so any configuration — origin, destination, HS2 commodity, cargo type, active tab — can be copied, shared, or bookmarked.
|
||
|
||
## The four tabs
|
||
|
||
Route Explorer is organized as four tabs, labelled in `src/components/RouteExplorer/RouteExplorer.ts`:
|
||
|
||
### 1. Current
|
||
|
||
The baseline route between the selected origin and destination, rendered on the map with chokepoint-crossing events highlighted. Shows which chokepoints the lane touches, live disruption score on each, and the live war-risk tier attached to the primary chokepoint.
|
||
|
||
### 2. Alternatives
|
||
|
||
Alternative maritime corridors if the primary lane is degraded — for example, Cape of Good Hope as a detour around the Suez + Bab-el-Mandeb system. Each alternative shows added transit days and an added-cost multiplier, filtered to corridors that are actually suitable for the selected cargo type.
|
||
|
||
### 3. Land
|
||
|
||
Land-corridor substitutions where a maritime lane has a credible rail or road counterpart (e.g. China–Europe via Middle Corridor). Useful for thinking through land-sea rebalancing rather than purely maritime detours.
|
||
|
||
### 4. Impact
|
||
|
||
Flips the question from "where does my cargo go" to "who is most exposed if this lane breaks." Ranks countries by import dependency on the selected HS2 chapter through the selected chokepoint.
|
||
|
||
## Inputs
|
||
|
||
All four tabs share a single input bar:
|
||
|
||
| Input | Values |
|
||
|---|---|
|
||
| **From country** | Any country; ISO-3166-1 alpha-2 under the hood. |
|
||
| **To country** | Same. |
|
||
| **HS2 commodity** | 2-digit HS chapter (e.g. `27` — mineral fuels). Default guesses from cargo type. |
|
||
| **Cargo type** | `container`, `tanker`, `bulk`, `roro` — filters bypass corridors to those that carry the cargo. |
|
||
|
||
Every change triggers a debounced re-fetch (~250ms) so holding a key or scrubbing through options feels live.
|
||
|
||
## Keyboard-first
|
||
|
||
Route Explorer is built for keyboard use — all inputs and tabs are reachable without the mouse. The full binding list is shown in the in-workflow help overlay (press `?`) and lives in `src/components/RouteExplorer/KeyboardHelp.ts`:
|
||
|
||
| Key | Action |
|
||
|---|---|
|
||
| `Esc` | Close the active picker first, then the panel |
|
||
| `Tab` / `Shift+Tab` | Move focus between the panel and the map |
|
||
| `F` | Jump to the From picker |
|
||
| `T` | Jump to the To picker |
|
||
| `P` | Jump to the Product (HS2) picker |
|
||
| `S` | Swap From ↔ To |
|
||
| `1` – `4` | Switch tabs (Current / Alternatives / Land / Impact) |
|
||
| `↑` / `↓` | Navigate the ranked list in the left rail |
|
||
| `Enter` | Commit the highlighted selection |
|
||
| `Cmd+,` | Copy the shareable URL |
|
||
| `?` | Show this help overlay |
|
||
|
||
## Map integration
|
||
|
||
While the workflow is open, the underlying map reflects your selections in real time:
|
||
|
||
- The primary route is highlighted.
|
||
- Bypass corridors render as dashed overlays when the Alternatives tab is active.
|
||
- The viewport zooms to fit the active route set.
|
||
|
||
When the workflow closes, the map restores its prior state.
|
||
|
||
## Tier & gating
|
||
|
||
Route Explorer is **PRO**. Free-tier visitors can open the workflow and fill in the input bar, but they hit a hard gate at fetch time — the left rail is blurred, the tab area is replaced with an "Unlock route intelligence" card and an **Upgrade to PRO** button, and no numeric payload is rendered in any tab. The underlying map, visible behind the modal, shows a generic public-route highlight as a preview of what PRO exposes.
|
||
|
||
The gate path is implemented by `renderFreeGate()` in `src/components/RouteExplorer/RouteExplorer.ts:342`; a `route-explorer:free-cta-click` analytics event fires if the Upgrade button is clicked. Clicking Upgrade routes into the Pro checkout (or falls back to the Pro marketing page).
|
||
|
||
## Data behind Route Explorer
|
||
|
||
- **Route graph** — `/api/supply-chain/v1/get-route-explorer-lane` (generated from `proto/worldmonitor/supply_chain/v1/`). Returns primary route id, chokepoint exposures, bypass corridors, war-risk tier, and disruption score.
|
||
- **Country impact** — `/api/supply-chain/v1/get-route-impact` for the Impact tab.
|
||
- **Chokepoint status** — live dry-bulk congestion, AIS density, dark-ship events, and recent incident feeds.
|
||
|
||
For the API-level contract, see the [Supply Chain](/api/SupplyChainService.openapi.yaml) and [Shipping v2](/api-shipping-v2) reference pages. For the underlying maritime layer on the map, see [Maritime Intelligence](/maritime-intelligence).
|
||
|
||
## Related workflows
|
||
|
||
- [Scenario Engine](/scenario-engine) — if Route Explorer answers "what is this lane today," Scenario Engine answers "what happens if a specific disruption event plays out."
|
||
- [Maritime Intelligence](/maritime-intelligence) — the layer-level view of vessels, chokepoints, and corridors on the main map.
|