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 / intelligence-products

Intelligence products

WorldMonitor turns monitored signals into products that help a user understand what is happening, what may happen next, and where action may be needed. The product set moves from source-grounded briefs and country views to risk scores, forecasts, scenarios, resilience views, company monitoring, orbital imagery, and decision support.

Product model

Signal-to-decision chain

The intelligence product flow starts with monitored observations and ends with a decision aid. Product services select relevant signals, add cross-domain context, and present an output with evidence and uncertainty so a user can judge it. Country views apply the same pattern across separate sections, while analyst context combines several product families for a focused question.

This diagram shows how monitored observations move through shared context into present-state views, risk measures, future views, company views, orbital imagery, and decision support.

flowchart LR
    A[Monitored observations] --> B[Signals and events]
    B --> C[Classified events]
    C --> D[Cross-domain context]
    D --> E[Briefs and analysis]
    D --> R[Country risk scores]
    D --> T[Tension monitoring]
    D --> O[Country coverage and observations]
    D --> F[Forecasts]
    D --> S[Scenarios]
    D --> G[Resilience views]
    D --> M[Company monitoring]
    D --> I[Orbital imagery]
    E --> Q[Decision support]
    R --> Q
    T --> Q
    O --> Q
    F --> Q
    S --> Q
    G --> Q
    M --> Q
    I --> Q

The products answer different questions rather than repeat the same view:

Product familyMain questionTypical output
Briefs and analysisWhat is happening and why does it matter?A cited brief, situation view, research result, or daily editorial issue
Country coverage and observationsWhat recent events and source observations are visible for this country?Headlines, incidents, signal observations, and source states
Country risk scoresWhere is instability concentrated and how is it changing?Scores, component signals, trends, and risk roll-ups
Tension monitoringWhich country pairs show notable pressure now?Pair scores, movement, and bounded evidence
ForecastsWhat is likely to happen next?A probability, trend, time horizon, and supporting case
ScenariosWhat could follow if a defined shock occurs?An impact result for affected countries or sectors
Resilience viewsHow well can a country absorb and recover from pressure?Scores, domains, coverage, confidence, and rankings
Company monitoringWhat is changing around a named company?Company context, signals, filings, and material events
Orbital imageryWhat can imagery show about activity or change at a place?Image evidence, pass windows, nearby event context, and geospatial views
Decision supportWhat should a user examine or consider next?Market, country, company, or supply-chain implications

References: src/…/InsightsPanel.ts• L223-258 src/…/CountryBriefController.ts• L14-66 proto/…/service.proto• L186-208 server/…/chat-analyst-context.ts• L986-1127 src/…/signal-aggregator.ts• L541-674

Product families

The product families form a reading path for a new engineer. Briefs explain the present state. Country coverage and observations show the source events behind it. Risk and tension views make pressure comparable. Forecasts and scenarios extend the view into possible futures. Resilience adds a longer-term capacity lens. Company monitoring, orbital imagery, and analyst outputs connect these views to named businesses, places, and decisions.

FamilyChild page
Brief generation, filtering, attribution, history, and analysisIntelligence briefs and analysis
Company enrichment, signals, filings, and material eventsCompany monitoring intelligence
Forecast ingestion and evaluation, scenario processing, and resilience scoringForecasting, scenarios, and resilience
Travel-risk assessment and trip-focused decision supportTravel-risk assessment
Orbital imagery and place-focused image intelligenceOrbital imagery intelligence

References: src/…/CountryBriefPanel.ts• L215-261 proto/…/service.proto• L15-42 proto/…/resilience.proto• L15-35 server/…/handler.ts• L38-74 docs/orbital-imagery-intelligence.md

Intelligence outputs

Briefs and analysis

Briefs turn selected signals into a short explanation of the current situation. World, country, and regional views can add source-linked news, risk, market, infrastructure, energy, and historical context. Country briefs publish supported claims in situation, implication, risk, outlook, and watch sections. Each claim must stay within its cited headline or data point, and the service keeps a fallback or unavailable state when the full analysis path cannot produce usable text.

The dashboard's Latest Brief surface presents a personalized daily editorial issue when it is ready. It can show a composing state while the issue is being prepared, or guide the user to sign in or use the required plan when access is not available. The issue is also delivered through the supported user channels, including email, Telegram, Slack, and the dashboard.

Analysis views connect signals across domains, compare the current situation with past events, or search durable intelligence history. Similar-event results provide precedents rather than predictions. Optional analysis frameworks change the structure of interpretation without changing the underlying signals.

See Intelligence briefs and analysis for generation, grounding, storage, and presentation flows.

References: server/…/get-country-intel-brief.ts• L74-93 server/…/get-country-intel-brief.ts• L181-256 server/…/get-country-intel-brief.ts• L481-643 server/…/get-similar-events.ts• L42-75 server/…/search-intel-history.ts• L38-78 src/…/country-intel.ts• L635-750 src/…/LatestBriefPanel.ts• L1-19 src/…/LatestBriefPanel.ts• L105-209

Country coverage and observations

Country coverage gives a country-focused view of recent headlines and incidents. It combines news with structured records such as protests, earthquakes, conflicts, military activity, and aviation disruption. It removes repeated reports and keeps source state beside the result, so a quiet period is distinct from a feed that failed or could not confirm its contents.

Country signal observations provide bounded access to selected source families for agents and other clients. Partial and unavailable states remain visible instead of becoming empty results.

References: server/…/_country-coverage-structured.ts• L39-55 server/…/_country-coverage-structured.ts• L133-205 server/…/get-country-signal-observations.ts• L16-72 src/…/country-intel.ts• L583-617

Country risk scores

Country risk scores provide a comparable view of instability across monitored countries. The Country Instability Index combines event pressure with security, information, climate, displacement, advisories, sanctions, disasters, military activity, and other monitored signals. It reports the score, component view, movement, trend, methodology version, and advisory source so a reader can see both the result and its basis.

The score can also support a strategic-risk roll-up based on the highest-risk countries. A trend is shown only when a valid earlier reading exists. A fresh response is preferred, while a failed refresh can return a stale snapshot or a low-information degraded result. Input health distinguishes missing, quiet, unavailable, and usable signal families, so missing inputs do not look like normal conditions.

References: server/…/classify-event.ts• L66-98 server/…/get-risk-scores.ts• L1271-1338 server/…/get-risk-scores.ts• L1691-1804 server/…/get-risk-scores.ts• L1875-1902 server/…/get-risk-scores.ts• L1918-1971 server/…/get-risk-scores.ts• L2281-2363 src/…/country-intel.ts• L483-489

Tension monitoring

The Pizzint status product provides a paired-country view of current tension. It combines a score and movement for configured pairs with notable evidence from channels such as strikes, airport status, military activity, and sanctions. Supporting evidence has its own freshness check, so a current score is not presented with stale observations.

References: server/…/get-pizzint-status.ts• L12-18 server/…/get-pizzint-status.ts• L21-83

Company monitoring

Company monitoring intelligence turns named-company context into a view of business exposure and change. It brings together company enrichment, company signals, filings, and material events so a user can connect a monitored development to a specific business.

See Company monitoring intelligence for the company-monitoring lifecycle and output details.

References: server/…/handler.ts• L18-24 server/…/handler.ts• L54-61

Forecasts and scenarios

Forecasts express possible future events as probabilities rather than facts. They can include a domain, region, time horizon, trend, signals, projected effects, alternative paths, and a rule for later resolution. Evaluation adds a track record while keeping unresolved, void, and audited outcomes distinct from verified accuracy.

Scenario workflows test a defined shock against supply-chain or market exposure. A request is accepted first, computed separately, and returned through a status query. The result reports whether its evidence is complete, partial, or unknown. Energy shock scenarios use measured crude imports and partner-level trade shares when available. They model bypass recovery for Saudi Arabia, the UAE, and Iraq rather than treating all Hormuz traffic as equally unrecoverable. A one-month ramp represents the early period before rerouting reaches its modeled level. Refinery output uses country-specific measured yields where available and a labeled global median for missing products. Product deficits use measured demand and trade data, with recent national demand data as a bounded fallback where the main source has no value. Missing origin or demand data is not replaced with a hidden fixed proxy. Shipping flow ratios remain context rather than a hidden change to scenario severity. Gas results are route sensitivities rather than country-specific shortage forecasts.

See Forecasting, scenarios, and resilience for forecast evaluation, scenario processing, and worker flows.

References: proto/…/forecast.proto• L7-18 src/…/ForecastPanel.ts• L332-585 proto/…/service.proto• L10-35 server/…/_hormuz-bypass.ts• L1-106 server/…/_shock-compute.ts• L101-177 server/…/_shock-compute.ts• L349-377 server/…/_shock-compute.ts• L535-570 server/…/compute-energy-shock.ts• L444-518 server/…/compute-energy-shock.ts• L566-697

Resilience views

Resilience views show how a country may absorb a shock and recover from it. The product combines several domains into an overall score and shows the domain view behind it. Coverage, freshness, confidence, and imputed data remain part of the result, so a score is read with its evidence limits.

See Forecasting, scenarios, and resilience for scoring, validation, ranking, and reporting workflows.

References: proto/…/resilience.proto• L17-38 src/…/ResilienceWidget.ts• L266-355 src/…/resilience-widget-utils.ts• L235-313 server/…/get-resilience-runtime-manifest.ts• L93-121

Travel-risk assessments

Travel-risk assessments turn monitored country conditions into trip-focused guidance. They connect current signals and country context to a travel decision, so the output supports questions about exposure, disruption, and precautions rather than only describing the general situation.

See Travel-risk assessment for the trip assessment workflow and its decision-support outputs.

References: docs/travel-risk-assessment.md

Orbital imagery intelligence

Orbital imagery intelligence adds image-based observations to the wider intelligence picture. It helps a user examine activity or change at a place and relate that visual evidence to monitored events and decision support.

The orbital watch view joins image evidence with time and place context. It can show confirmed acquisitions, likely or possible collection passes, the latest usable image, image history, daily mosaics, weather frames, and upcoming collection windows. Nearby events and live activity appear beside the imagery, while watched-site records add a place-specific view when one exists. Archive, freshness, processing, no-data, and partial-source states remain visible so the user can tell an absent image from an absent observation.

See Orbital imagery intelligence for the imagery workflow and its outputs.

References: src/…/OrbitalWatchPage.ts• L888-985 src/…/OrbitalWatchPage.ts• L988-1107 src/…/OrbitalWatchPage.ts• L1130-1177 src/…/OrbitalWatchPage.ts• L1180-1201 docs/orbital-imagery-intelligence.md

Decision-support outputs

Decision support combines a present-state explanation with a forward view or an impact lens. A country view can place a brief beside risk, signals, markets, infrastructure, energy, trade, and resilience context. Its energy view can show the mix, import dependence, storage, electricity, oil and gas measures, strategic reserves, and regional feed status. Energy values can come from data with different update times, while each unavailable or partial measure stays labeled. Port activity adds tanker movement and anomaly context when coverage is available. A decision brief can turn selected disruption or commodity-route assumptions into a conditional impact with evidence, assumptions, unknowns, and a next action.

The analyst context supports questions that need more than one product family. It can combine risk, forecasts, market implications, prediction markets, macro signals, headlines, and energy measures. Situation deduction can add matched prediction-market odds to a query and apply a caller-selected analysis framework for premium users. Market titles are treated as data, not instructions, before they enter the analysis context. The streamed analyst response checks stated prices against the live context. If an answer states a price that the context does not support, it adds a visible caveat instead of silently presenting the figure as current.

Country intelligence opens from the map or another client request. The country panel shows an early country view, then fills in signals, coverage, economics, infrastructure, and brief text. Request ownership and country identity checks prevent an older or invalid request from replacing the active view.

References: server/…/chat-analyst-context.ts• L986-1127 server/…/chat-analyst-grounding.ts• L97-132 server/…/chat-analyst-grounding.ts• L134-193 server/…/deduct-situation.ts• L50-88 server/…/deduct-situation.ts• L105-197 server/…/get-country-energy-profile.ts• L312-393 server/…/get-country-energy-profile.ts• L396-515 server/…/get-country-port-activity.ts• L73-126 server/…/compute-energy-shock.ts• L421-470 src/…/country-intel.ts• L421-507 src/…/country-intel.ts• L549-717

Product trust and delivery

Evidence and uncertainty

The products separate an observation from an interpretation. Briefs keep source links and validate claims. Event classification accepts only known threat levels and categories. Scores, markets, forecasts, tension evidence, resilience values, and country sections carry freshness, coverage, or grounding limits. Analyst context treats feed text as data rather than instructions, and price grounding marks unsupported streamed figures for the reader.

The signal layer also keeps different observations distinct before they reach product context. It normalizes events to countries, groups them by country and region, limits the retained window and total volume, and derives convergence from signal variety, count, and severity. This lets downstream analysis see cross-domain activity without treating every raw event as a separate high-level conclusion.

This trust model also affects empty and partial results. A healthy system with no matching signal is different from a missing source or a failed service. Product responses therefore use states such as degraded, stale, unavailable, pending, or low confidence instead of silently turning missing data into a quiet conclusion.

References: server/…/classify-event.ts• L44-64 server/…/classify-event.ts• L146-184 server/…/chat-analyst-grounding.ts• L88-119 server/…/chat-analyst-grounding.ts• L146-166 server/…/get-pizzint-status.ts• L21-83 server/…/get-risk-scores.ts• L1127-1199 server/…/get-country-energy-profile.ts• L403-429 server/…/compute-energy-shock.ts• L251-277 src/…/country-intel.ts• L759-799 src/…/signal-aggregator.ts• L103-140 src/…/signal-aggregator.ts• L534-619

Composite analysis inputs

Composite analysis turns several seeded or cached source payloads into a shared digest input. The adapters keep source absence as unavailable data, reject malformed coordinates and unsupported event locations, map source-specific severity to common levels, and preserve the distinction between a measured value and a missing one. This gives alert and decision products one stable input shape without hiding gaps in the source feeds.

References: shared/analysis-composite-adapters.ts• L41-71 shared/analysis-composite-adapters.ts• L73-163 shared/analysis-composite-adapters.ts• L165-250 shared/analysis-composite-adapters.ts• L252-272

Precomputed and on-demand work

The product set uses precomputed material for common views and on-demand work for questions that depend on the current user or a costly calculation. This keeps the dashboard fast while preserving deeper analysis when a user opens a view or asks a question.

Common briefs, forecasts, scores, and resilience data can come from shared snapshots. Historical searches, analyst questions, country coverage, signal observations, and decision calculations run when requested. Situation deduction uses a bounded request budget and caches successful context-specific results. Scenario and simulation work runs asynchronously, then returns a result through polling.

References: src/…/insights-loader.ts• L61-123 src/…/forecast.ts• L30-48 server/…/search-intel-history.ts• L24-73 server/…/deduct-situation.ts• L90-103 server/…/deduct-situation.ts• L123-190 server/…/get-scenario-status.ts• L62-97 src/…/country-intel.ts• L595-617

Access and product surfaces

Some intelligence products are public summaries. Deeper briefs, historical research, analyst conversations, scenarios, simulations, and resilience views use access rules enforced by the service layer. The daily Latest Brief is an account-linked, Pro-gated product that can be ready, composing, or unavailable without exposing another user's content. The same product can appear in a dashboard panel, a country view, a report, an API response, or an MCP response, so each surface must preserve the same meaning and access state.

References: src/…/LatestBriefPanel.ts• L105-209 src/…/LatestBriefPanel.ts• L224-345 src/…/LatestBriefPanel.ts• L393-445 src/…/ResilienceWidget.ts• L170-235 server/…/run-scenario.ts• L28-36 api/chat-analyst.ts• L129-172 src/…/country-intel.ts• L227-249

Change checklist

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

  • When a monitored signal or snapshot shape changes, update selection, provenance, freshness, and degraded-state handling together.
  • When signal types or convergence rules change, keep country normalization, regional membership, severity mapping, retention limits, AI context, and digest adapters aligned.
  • When event classification labels change, keep the allowed levels, categories, severity mapping, cache namespace, and downstream risk interpretation aligned.
  • When composite analysis inputs change, keep null propagation, source field mapping, coordinate validation, exposure grouping, and shared severity bands aligned.
  • When a country brief grounding source changes, check source dates, cache sharing, evidence limits, citation validation, and fallback behavior together.
  • When a country view changes, keep country identity, request ownership, section state, access gates, and exported decision content aligned.
  • When analyst context changes, keep domain selection, headline scope, feed sanitization, active-source labels, and degraded state aligned.
  • When analyst price grounding changes, keep currency matching, rounding tolerance, streamed completion handling, and visible caveat behavior aligned.
  • When situation deduction changes, keep prediction-market selection, prompt-safe feed text, framework access, cache identity, timeout degradation, and quota release aligned.
  • When country energy data changes, keep spine and fallback sources, regional feed status, per-series freshness, coverage flags, and cache-read failure behavior aligned.
  • When country port activity changes, keep country allowlisting, current and servable age limits, stale labeling, and the bounded port list aligned.
  • When an energy shock input changes, keep partner-level trade coverage, measured crude imports, bypass assumptions, ramp timing, refinery yield basis, product demand fallback, route factors, coverage labels, limitations, cache versions, and oil or gas mode behavior aligned.
  • When forecast or scenario fields change, check the service contract, published data, worker result, coverage state, and reader together.
  • When a resilience dimension or score formula changes, align score validity, confidence, ranking eligibility, and runtime metadata.
  • When risk inputs or scoring weights change, align the formula version, methodology disclosure, input-health report, trend history, strategic roll-up, and stale fallback.
  • When the daily brief's status or access rules change, keep account identity, entitlement state, signed-link delivery, composing refresh, and locked or unavailable states aligned.
  • When orbital evidence or point context changes, keep pass tiers, archive results, image fallbacks, nearby event states, source credits, freshness labels, and watched-site records aligned.

Important failure modes

TriggerConsequenceGuard
A required source snapshot is missing or too oldA product can become unavailable or degraded, or show a score with weak confidence.Validate freshness and carry explicit source state in the output.
A signal payload has an unknown country, invalid location, or unsupported shapeEvents can be grouped under the wrong place or omitted from exposure and digest context.Normalize country codes, validate coordinates, and reject unsupported records before grouping.
Signal volume exceeds the retained window or capOld or low-priority events can crowd out current activity and distort convergence.Prune signals by age and retain only the newest bounded set.
A headline has an invalid or unsupported classification resultThe event can disappear from the classification response or lose its intended risk priority.Limit the input, validate the returned level and category, and return an undefined classification on failure.
A streamed analyst answer states a price absent from live contextA user may treat an old or invented price as current.Compare prices by currency and tolerance, then append a visible unverified caveat before completion.
A country request has an invalid code or finishes after the user changes countryThe wrong country can open or old data can replace the active view.Canonicalize country codes and check request ownership before applying results.
A country coverage feed fails or has no usable itemsA client can mistake a source failure for a quiet country.Keep failed, unknown, empty, and usable states distinct.
A regional energy feed is malformed or outside its freshness windowA country energy view can present invalid or stale regional measures as current.Validate feed records and periods, mark each feed state, and preserve partial coverage.
An energy profile cache read failsA client can receive a successful-looking profile with false availability.Return a service error and avoid publishing the profile as complete.
Port activity is not allowlisted or passes its serving ageA country view can expose an unsupported country or show a month-old movement window as current.Apply the country allowlist and separate current, stale, and no-longer-servable payloads.
Situation deduction times out or its provider failsA user receives no analysis after the request budget is spent.Bound the reasoning call, cache successful context-specific results, and return an explicit error state.
Crude imports or partner-level origin shares are unavailableAn oil shock can look complete while its loss and product deficits are not measured.Do not use a fixed proxy. Report unsupported or incomplete coverage with explicit limitations.
Bypass capacity or its date is changed without the loss and cover logicThe scenario can use one assumption for exposure and another for stock cover.Keep exporter assumptions, ramp timing, cache inputs, limitations, and assessment text aligned.
Refinery yield or product demand data is missing or staleProduct deficits can look measured when they use a weak or mismatched basis.Use a labeled fallback only where allowed and keep the source window and coverage in the result.
A gas shock result is read as a shortage forecastA route sensitivity can be treated as measured country exposure.Label the result as an assumed route sensitivity and show its data limits.
An asynchronous scenario is accepted but not completeA user can read an accepted job as a finished impact result.Return pending status and poll until completion or failure.
Forecast evidence is too small, stale, or under auditThe product can show a reliability number that the data cannot support.Gate scorecards and keep unresolved or audited outcomes separate from verified grades.
A risk input read fails during score refreshA partial recomputation can hide a source failure or replace a usable snapshot with bad data.Reject the fresh build, keep the last good snapshot, and mark the response degraded and stale.
A risk score has no valid prior readingThe reader can mistake an unknown movement for a stable score.Use an unspecified trend until a valid time-matched comparison exists.
A brief request crosses an account or entitlement changeOne user's issue can be shown to another user, or a valid user can see a false upgrade prompt.Bind the request to the current account, enforce access on the server, and check the result before display.
Brief composition has not finished or its service cannot be reachedThe panel can imply that no brief exists or leave a user waiting without a clear state.Show composing, sign-in, upgrade, desync, and service-error states separately.
An orbital archive, orbit catalog, or nearby-event source is stale or unavailableA point view can look empty even though the source failed, or can present old evidence as current.Mark source state and freshness separately, then preserve partial results and retry paths.
An image has no data at the point or is still processingA missing crop can look like a failed acquisition or a confirmed absence of activity.Use archive fallbacks and explicit no-data or processing states.

Key files

FileWhy to read it
proto/…/service.protoDefines the main intelligence service contract.
server/…/handler.tsShows the service surface for briefs, country observations, company monitoring, and decision support.
src/…/country-intel.tsShows how a country selection becomes a layered country intelligence view.
src/…/signal-aggregator.tsShows how current geographic signals become country clusters, regional convergence, and AI context.
shared/analysis-composite-adapters.tsShows how source payloads become common inputs for composite alert analysis.
server/…/classify-event.tsShows how monitored headlines receive bounded threat and category labels.
server/…/get-country-intel-brief.tsShows the country brief output and its evidence boundary.
src/…/LatestBriefPanel.tsShows the daily brief surface, its account and plan states, and its transition from composing to ready.
server/…/get-risk-scores.tsShows how monitored signals become country scores, trends, health states, and strategic risk.
server/…/chat-analyst-context.tsShows how cross-domain context is assembled for analyst questions.
server/…/chat-analyst-grounding.tsShows how streamed price claims are checked against live context.
server/…/deduct-situation.tsShows how on-demand situation analysis uses query context and prediction-market signals.
server/…/get-country-energy-profile.tsShows how country energy measures and regional feed states become decision context.
server/…/_regional-energy-feeds.tsDefines regional energy feed validation, freshness, and availability states.
server/…/get-country-port-activity.tsShows how bounded port activity becomes country context with stale handling.
server/…/_hormuz-bypass.tsDefines the dated bypass assumptions that limit modeled Hormuz oil loss.
server/…/_shock-compute.tsDefines shared coverage, refinery, product-balance, stock-cover, and gas-sensitivity rules for shock scenarios.
server/…/compute-energy-shock.tsShows how trade, energy, storage, bypass, and chokepoint data shape an energy scenario.
src/…/OrbitalWatchPage.tsShows how a place-focused imagery view combines acquisitions, passes, archives, events, and source states.
proto/…/forecast.protoDefines forecast claims, evidence, and resolution.
proto/…/service.protoDefines the asynchronous scenario request and status flow.
proto/…/resilience.protoDefines resilience domains, coverage, and ranking eligibility.
api/chat-analyst.tsShows the external streamed analyst surface.
docs/travel-risk-assessment.mdExplains the trip-focused assessment workflow and its output.
docs/orbital-imagery-intelligence.mdExplains the place-focused imagery workflow and its intelligence output.