Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / web-application-shell

Web application shell and composition

World Monitor uses a set of focused browser surfaces around one shared web product. The main dashboard provides the full monitoring workspace, while settings, live channels, embeds, browser-plugin views, MCP consent, and claim verification start only the services needed for their task. See client experience for the wider client model and monitoring dashboards for dashboard behavior.

Surface entrypoints

Each page starts from a dedicated browser entrypoint. The main entry prepares shared browser services and chooses between the dashboard and focused management windows. Separate plugin and verification entrypoints keep host-facing and public workflows independent from the full dashboard.

flowchart TD
    Request[Browser request] --> Surface{Web surface}
    Surface --> Dashboard[Primary dashboard]
    Surface --> Focused[Settings or live channels]
    Surface --> Embed[Partner embed]
    Surface --> Grant[MCP consent]
    Surface --> PluginNews[Browser-plugin news view]
    Surface --> PluginCountry[Browser-plugin country view]
    Surface --> Verify[Claim verification]
    Dashboard --> Main[src/main.ts]
    Main --> App[App composition]
    Focused --> Main
    PluginNews --> Plugin[Plugin composition]
    PluginCountry --> CountryPlugin[Country plugin composition]
    Verify --> VerifyEntry[src/verify-main.ts]

Primary dashboard

The primary dashboard starts the full monitoring workspace. src/main.ts prepares presentation, request routing, reporting, service-worker behavior, and the WebMCP boundary before App creates the map and panel system. App owns the WebMCP controller during initialization, so a failed boot can remove agent tools and destroy the partial workspace before the shell shows the failure state. Deep links can select a country, story, chokepoint, search, or stock research view.

References: src/main.ts• L700-746 src/App.ts• L2600-2636 src/App.ts• L3829-3915

Focused web surfaces

Settings and live-channel management avoid constructing the full dashboard. URL flags select their focused startup after localization is ready. The settings window manages saved product choices and feature readiness. The live-channel window manages built-in regional channels and user-defined sources. The embed and MCP grant pages serve partner display and authorization workflows without carrying the main map and panel lifecycle.

References: src/main.ts• L676-699 src/settings-main.ts• L872-974 src/live-channels-window.ts• L48-73 src/…/embed-url.ts• L221-235 src/mcp-grant-main.ts• L45-105

Claim verification surface

The /verify surface gives signed-out users a shareable way to check whether World Monitor sources report a claim. It searches fresh headline caches and builds a coverage card that describes publishers and stated figures without judging whether the claim is true. Published fact-check results load beside the coverage result and do not replace it. A claim in the URL makes the result reproducible and supports browser history navigation.

References: verify.html• L81-114 src/verify-main.ts• L23-47 src/verify-main.ts• L61-130 src/…/verify-claim.ts• L19-24 src/…/verify-claim.ts• L77-134

Web build delivery

The web build keeps the dashboard, focused windows, embeds, MCP consent, and verification as separate browser paths while sharing common code where that does not increase the critical startup cost. The dashboard applies its large stylesheet after the first paint and loads heavy views when they are needed. Service-worker registration waits until after the first paint, then supports later update checks for web users while avoiding desktop and unsafe browser contexts.

References: src/main.ts• L35-53 src/main.ts• L586-620 src/main.ts• L764-856 vite.config.ts• L302-323 vite.config.ts• L1007-1138

Dashboard composition

App is the central coordinator for the primary dashboard. It gives layout, data, user actions, country views, account state, and refresh work one shared application state so the map and panels respond to the same preferences and lifecycle.

Application lifecycle

The dashboard starts in stages. It opens browser storage and translations, localizes the document shell, creates the visible map-and-panel workspace, and prepares account and network state. Fast bootstrap data supports early content. A bounded wait gives slower bootstrap data time to arrive before the visible-data fan-out; if it does not arrive, the dashboard continues and loads visible panels through their normal paths. Below-fold panels load when they approach the viewport.

Slower intelligence work runs after the first usable workspace. Country geometry supports later country analysis, and the correlation engine loads independently after the initial data pass. Optional local AI also starts in the background and does not block layout or basic panels. Connectivity state distinguishes live, cached, and unavailable data so the workspace can explain a degraded start.

The lifecycle keeps access state attached to the running workspace. Account and entitlement changes reconcile saved limits and premium data after the active account is known. Sign-out or downgrade clears account-bound data instead of leaving it visible. Destroying the application first invalidates detached work and agent access, then cancels waits, removes listeners, stops background work, and tears down managers and map services.

flowchart LR
    Runtime[Prepare browser runtime] --> Storage[Open local storage and translations]
    Storage --> Workspace[Create map and panels]
    Workspace --> Fast[Hydrate fast bootstrap data]
    Fast --> Slow[Wait for bounded slow-tier checkpoint]
    Slow --> Visible[Load visible data]
    Visible --> Background[Load geometry and intelligence work]
    Background --> Refresh[Start refresh work]
    Refresh --> Access[Reconcile account access]
    Access --> Running[Running dashboard]
    Running --> Destroy[Cancel and tear down]
    Workspace -. independent .-> LocalAI[Optional local AI]

References: src/App.ts• L2600-2636 src/App.ts• L2660-2801 src/App.ts• L2803-2831 src/App.ts• L2089-2134 src/App.ts• L3262-3305 src/App.ts• L3829-3915

Shared dashboard managers

The shell assigns separate responsibilities to managers while keeping their state connected through AppContext. Layout owns the workspace. Data loading supplies panel content. Event handling links user actions to URL and saved state. Country intelligence supports country views. Refresh scheduling keeps active data current. This separation lets one surface coordinate many product views without giving each panel its own application lifecycle.

Account and entitlement changes use the same manager links. The dashboard re-runs premium loaders when access becomes available and removes account-bound results when access ends. Country results and other delayed work check the current application and selection before publishing, so a late response cannot replace newer user state.

References: src/App.ts• L1700-1847 src/App.ts• L2831-3106 src/…/app-context.ts• L29-149 src/…/country-intel.ts• L179-244 src/…/event-handlers.ts• L270-454 src/…/data-loader.ts• L1263-1365

Panel and tab composition

Panel layout turns the active variant, saved settings, and account access into a responsive map-and-panel workspace. It supports multiple dashboard tabs, user panel order, collapsed and full-screen states, and deferred heavy panels. Each tab owns its panel selection and focus state, while shared map state remains outside the tab snapshot. Teardown removes observers, timers, controls, and panel resources when the dashboard is replaced.

References: src/…/panel-layout.ts• L259-419 src/…/panel-layout.ts• L817-942 src/…/panel-layout.ts• L1032-1329 src/…/panel-layout.ts• L1960-2137

Focus and map synchronization

Dashboard focus defines the countries that the active tab is about. The shared focus state narrows panel presentation and drives map outlines and fitting. A saved team map view takes priority over automatic fitting, while focus outlines remain visible. The sync waits for the map to exist and drops superseded movement so user navigation stays in control.

References: src/…/focus-map-sync.ts• L3-82 src/…/tab-focus.ts• L22-107 src/…/panel-layout.ts• L1636-1667 src/…/MapContainer.ts• L1900-1930

Agent dashboard interface

WebMCP gives an AI client a controlled interface to inspect and operate the dashboard. It exposes the current map, panels, layers, mission presets, monitor navigation, settings actions, and country views through the same managers used by the human UI. Access checks include account focus and plan access, so the agent sees only actions the current workspace can use.

Actions wait for their owning UI manager and report denied, unavailable, invalid, applied, or unchanged outcomes. They wait for UI and map readiness when needed. App teardown aborts registration, resolves pending waits, and prevents a replaced dashboard from accepting actions.

References: src/App.ts• L2216-2597 src/App.ts• L2600-2606 src/App.ts• L4021-4057 src/…/webmcp-dashboard.ts• L71-160 src/…/webmcp-dashboard.ts• L316-526

Shared runtime services

The shell places common browser concerns around each surface-specific startup. These services set presentation state early, route requests to the correct runtime, collect useful failure and performance signals, and recover from stale deployed assets.

Presentation state

The shell applies theme, variant, font, and font scale before the dashboard is constructed. After translations load, it updates the document title, description, social metadata, and accessible heading. This keeps the first visible frame close to the user’s saved presentation while larger dashboard styles load later.

References: src/main.ts• L646-670 src/App.ts• L2631-2658 src/main.ts• L35-53

Request routing and recovery

The browser installs request attribution and runtime routing before dashboard data work begins. Web deployments use the web API route, while desktop deployments can use a local sidecar. Stale chunk checks and service-worker update checks help an open tab move to a current build after deployment. A boot error is reported, the partial app is destroyed, and the user receives a clear failure screen.

References: src/main.ts• L628-644 src/main.ts• L709-746 src/App.ts• L2763-2801 src/App.ts• L3829-3915

Error and performance reporting

The shell buffers early errors until deferred monitoring services are ready. It reports page and interaction timing and filters known browser-generated policy noise before sending useful violations to telemetry. Sensitive URL values are removed before analytics vendors start.

References: src/main.ts• L56-75 src/main.ts• L84-566 src/main.ts• L609-623

Partner embed composition

The embed surface is a small World Monitor view for a partner page. URL values select the panel, layers, center, zoom, theme, and variant. The surface normalizes these values before mounting the view and reports clear ready or error states to its parent frame.

Embed access and data flow

The embed paints a public view first. If the parent supplies a partner key, the browser exchanges it for a short-lived grant and upgrades the existing view. The frame response controls data readiness, granted layers, and refresh timing. Paid panels check entitlement before rendering, so denied access is visible rather than appearing as incomplete data.

sequenceDiagram
    participant Parent as Partner page
    participant Embed as Embed view
    participant Grant as Grant service
    participant Frame as Frame service
    Parent->>Embed: Supply view parameters
    Embed->>Frame: Request public frame
    Frame-->>Embed: Data and layer state
    Embed-->>Parent: Show public view
    Parent->>Embed: Supply partner key
    Embed->>Grant: Exchange key
    Grant-->>Embed: Grant or denial
    Embed->>Frame: Request granted frame
    Frame-->>Embed: Entitled data and refresh timing

References: src/…/embed-url.ts• L11-29 src/…/embed-url.ts• L168-235 src/…/embed-fetch.ts• L99-187 src/…/embed-data-loader.ts• L102-175 src/…/map.ts• L18-77

Embed failure handling

The embed keeps terminal denial separate from temporary service failure. A denied grant returns to the public view. A temporary renewal or frame failure keeps the last usable display and retries later. Keyed requests omit browser cookies so the viewer’s World Monitor account does not become the partner identity.

References: src/…/embed-fetch.ts• L15-71 src/…/embed-data-loader.ts• L178-281

Browser-plugin composition

Browser-plugin composition adapts shared World Monitor views to a host that can provide data, tools, and link actions. The plugin does not own the upstream intelligence services. It validates host messages and turns them into visible news, map, and country-brief state.

News and map view

The news view combines a host-provided news snapshot with panels, filters, search, and map state. It can request a bounded hazard snapshot for natural events or fires and reports effective filters, map state, and data coverage back to the host. Partial or stale data remains visible with an explicit status.

References: src/plugin-main.ts• L32-145 src/plugin-main.ts• L151-217 src/plugin-main.ts• L234-372 src/…/plugin-map-snapshot.ts• L44-85

Country brief view

The country view turns a host-selected country into a source-backed brief. Sections load independently, so an unavailable assessment or signal does not hide sections that remain usable. Revision and cancellation checks keep late results from an earlier country out of the current brief. The view reports section state and source context to the host and uses host capabilities for links, downloads, and model context.

The host handshake establishes tools, link opening, display mode, and model-context support before the view reports readiness. Host actions can change the country, topic, or selected energy asset. Context updates are bounded and marked as acknowledged only when the host confirms them.

References: src/plugin-country-main.ts• L354-440 src/plugin-country-main.ts• L442-532 src/plugin-country-main.ts• L629-787 src/plugin-country-main.ts• L789-914

Focused management and consent pages keep short workflows separate from the main dashboard. They reuse shared language, account, and network rules where needed, but they do not carry the full map and panel lifecycle.

Settings and live-channel management

The settings surface controls product and presentation choices that the dashboard reads later. It groups optional feature switches and service secrets by product area, shows readiness, and lets users search settings. Values stay staged until required fields and service checks pass, then the surface commits them as one save action.

The live-channel surface controls the saved channel list used by the live news experience. It supports regional built-in channels and custom video and secure HLS sources. Users can search, add, remove, edit, restore, and reorder entries. Source type and secure transport are checked before save.

References: src/main.ts• L676-699 src/settings-main.ts• L84-145 src/settings-main.ts• L288-394 src/settings-main.ts• L780-974 src/live-channels-window.ts• L48-83 src/live-channels-window.ts• L293-425

The MCP consent surface confirms an external AI client’s requested access. It uses a URL nonce and a live session to load request details, then follows only a trusted server redirect after approval. Signed-out users receive a sign-in path. Context and optional profile questions can load separately so the consent action remains available when non-essential data is slow.

References: src/mcp-grant-main.ts• L1-22 src/mcp-grant-main.ts• L45-105 src/mcp-grant-main.ts• L138-249 src/mcp-grant-main.ts• L388-549

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the dashboard entry, deferred stylesheet marker, output document, and production route rewrite aligned.
  • Keep focused URL flags separate from normal dashboard startup so settings and live-channel windows do not construct App.
  • Keep WebMCP registration, app binding readiness, action readiness, viewport settling, and teardown aligned.
  • Keep AppContext fields and manager callbacks aligned so layout, data, event, country, account, and refresh managers share live state.
  • Keep bootstrap hydration before the first visible-data fan-out so one-time data is not missed.
  • Keep the slow-tier timeout path and the later viewport-trigger path aligned so below-fold panels still load after a degraded bootstrap.
  • Keep account handoff ordering aligned with entitlement and premium loader fan-out so one account cannot retain another account’s data.
  • Keep optional local AI continuations behind current settings, boot epochs, and app-lifetime checks.
  • Keep service-worker registration, stale-bundle recovery, API routing, and cache behavior aligned with the shell each surface needs.
  • Keep embed URL aliases, layer IDs, public requests, grants, response readiness, and refresh timing aligned.
  • Keep plugin host initialization, capability checks, message validation, revision guards, model-context limits, and pagehide cleanup aligned.
  • Keep verification URL state, latest-run guards, coverage results, and fact-check results separate so stale work cannot overwrite a newer claim.
  • Keep trusted redirect validation and nonce handling aligned with the MCP authorization service.

Important failure modes

TriggerConsequenceGuard
Dashboard boot fails after WebMCP registrationAn AI client can call tools bound to a dead applicationDestroy the partial App and abort its WebMCP controller before showing the boot failure
Visible data fan-out runs before slow bootstrap hydrationOne-time data is missed and panels make avoidable requestsWait for the bounded slow-tier checkpoint before the initial fan-out
Slow bootstrap times out and no later viewport pass runsBelow-fold panels can remain empty after the first usable viewKeep the deferred fan-out and arm scroll and resize triggers after the initial pass
Optional local-AI work resolves after the app is destroyedA dead app can download a model or restart shared worker stateInvalidate the boot epoch and check app lifetime before each continuation acts
Account access changes without clearing or reloading account-bound dataA user can see stale premium or prior-account resultsReconcile access after account handoff and clear data on downgrade or sign-out
A late country result ignores revision or cancellation stateThe brief shows data for an earlier countryCheck the active country, revision, abort signal, and app lifetime before publishing
A keyed embed request includes browser cookiesThe viewer’s account can become the partner identityOmit credentials from keyed frame requests
A temporary embed failure is treated as terminal denialA paid view drops to the public layer set during a short outagePreserve the last usable frame and retry temporary failures
A plugin host returns malformed data or denies a required capabilityThe embedded view can show the wrong state or fail without explanationValidate host records, track capability state, and expose unavailable or unconfirmed status
A stale verification search resolves after a newer claimResults for an earlier claim replace the current resultGate every status and render update with the latest run identifier
Fact-check lookup failure is treated as no matching fact checksA service outage looks like evidence that no fact check existsReturn an explicit unavailable state and render it separately from an empty result
Consent follows an untrusted redirectThe authorization flow can send the user to an attacker-controlled hostAccept only the trusted API origin returned by the authorization contract

Key files

FileWhy to read it
src/main.tsShows shared browser startup, focused surface selection, dashboard boot, routing, reporting, stale-build recovery, and service-worker timing.
src/App.tsShows central dashboard lifecycle, staged bootstrap and viewport loading, manager composition, account handoff, WebMCP bindings, optional local AI, and teardown.
src/…/app-context.tsDefines the shared dashboard state contract used by the map, panels, data, country views, account state, and refresh work.
src/…/panel-layout.tsShows map and panel composition, tabs, deferred panels, focus, persistence, access gates, and cleanup.
src/…/data-loader.tsShows staged bootstrap use and viewport-aware loading for dashboard content.
vite.config.tsShows web entrypoints, output variants, deferred styles, lazy delivery, and service-worker policy.
src/…/embed-url.tsDefines the partner view contract and accepted URL and snippet forms.
src/…/embed-fetch.tsDefines public frame requests, grant exchange, retry meaning, and credential boundaries.
src/…/embed-data-loader.tsShows how an embed applies frame data, changes access tier, refreshes, and preserves usable state.
src/plugin-main.tsShows the plugin news and map lifecycle, host messages, shared UI composition, and cleanup.
src/plugin-country-main.tsShows country selection, independent brief sections, host capability use, bounded context, cancellation, and cleanup.
src/verify-main.tsShows the claim verification workflow, shareable URL state, independent fact-check loading, and stale-result protection.
src/…/verify-claim.tsDefines claim search and fact-check contracts and the difference between unavailable and empty results.
src/mcp-grant-main.tsShows MCP sign-in, consent, context loading, retry handling, and trusted redirect flow.