World Monitor v2

AI-powered real-time global intelligence dashboard aggregating news, markets, geopolitical data, and infrastructure monitoring into a unified situation awareness interface.

🌐 Live Demo: worldmonitor.app | 💻 Tech Variant: tech.worldmonitor.app

Platform Variants

World Monitor runs two specialized variants from a single codebase, each optimized for different monitoring needs:

A compact variant switcher in the header allows seamless navigation between variants while preserving your map position and panel configuration.

World Monitor (Geopolitical)

The primary variant focuses on geopolitical intelligence, military tracking, and infrastructure security monitoring.

Key Capabilities

• Conflict Monitoring - Active war zones, hotspots, and crisis areas with real-time escalation tracking
• Military Intelligence - 220+ military bases, flight tracking, naval vessel monitoring, surge detection
• Infrastructure Security - Undersea cables, pipelines, datacenters, internet outages
• Economic Intelligence - FRED indicators, oil analytics, government spending, sanctions tracking
• Natural Disasters - Earthquakes, severe weather, NASA EONET events (wildfires, volcanoes, floods)
• AI-Powered Analysis - Focal point detection, country instability scoring, infrastructure cascade analysis

Intelligence Panels

News Coverage

80+ curated sources across geopolitics, defense, energy, think tanks, and regional news (Middle East, Africa, Latin America, Asia-Pacific).

Tech Monitor

The tech variant (tech.worldmonitor.app) provides specialized layers for technology sector monitoring.

Tech Ecosystem Layers

Tech Infrastructure Layers

Tech News Categories

• Startups & VC - Funding rounds, acquisitions, startup news
• Cybersecurity - Security vulnerabilities, breaches, threat intelligence
• Cloud & Infrastructure - AWS, Azure, GCP announcements, outages
• Hardware & Chips - Semiconductors, AI accelerators, manufacturing
• Developer & Open Source - Languages, frameworks, open source projects
• Tech Policy - Regulation, antitrust, digital governance

Regional Tech HQ Coverage

Features

Interactive Global Map

• Zoom & Pan - Smooth navigation with mouse/trackpad gestures
• Regional Focus - 8 preset views for rapid navigation (Global, Americas, Europe, MENA, Asia, Latin America, Africa, Oceania)
• Layer System - Toggle visibility of 20+ data layers organized by category
• Time Filtering - Filter events by time range (1h, 6h, 24h, 48h, 7d)
• Pinnable Map - Pin the map to the top while scrolling through panels, or let it scroll with the page
• Smart Marker Clustering - Nearby markers group at low zoom, expand on zoom in

Marker Clustering

Dense regions with many data points use intelligent clustering to prevent visual clutter:

How It Works

• Markers within a pixel radius (adaptive to zoom level) merge into cluster badges
• Cluster badges show the count of grouped items
• Clicking a cluster opens a popup listing all grouped items
• Zooming in reduces cluster radius, eventually showing individual markers

Grouping Logic

• Protests: Cluster within same country only (riots sorted first, high severity prioritized)
• Tech HQs: Cluster within same city (Big Tech sorted before unicorns before public companies)
• Tech Events: Cluster within same location (sorted by date, soonest first)

This prevents issues like Dubai and Riyadh companies appearing merged at global zoom, while still providing clean visualization at continental scales.

Data Layers

Layers are organized into logical groups for efficient monitoring:

Geopolitical

Military & Strategic

Infrastructure

Transport

*AIS data via AISStream.io uses terrestrial receivers with stronger coverage in European/Atlantic waters. Middle East, Asia, and open ocean coverage is limited. Satellite AIS providers (Spire, Kpler) offer global coverage but require commercial licenses.

Natural Events

Economic & Labels

Intelligence Panels

Beyond raw data feeds, the dashboard provides synthesized intelligence panels:

These panels transform raw signals into actionable intelligence by applying scoring algorithms, trend detection, and cross-source correlation.

News Aggregation

Multi-source RSS aggregation across categories:

• World / Geopolitical - BBC, Reuters, AP, Guardian, NPR, Politico, The Diplomat
• Middle East / MENA - Al Jazeera, BBC ME, Guardian ME, Al Arabiya, Times of Israel
• Africa - BBC Africa, News24, Google News aggregation (regional & Sahel coverage)
• Latin America - BBC Latin America, Guardian Americas, Google News aggregation
• Asia-Pacific - BBC Asia, South China Morning Post, Google News aggregation
• Energy & Resources - Google News aggregation (oil/gas, nuclear, mining, Reuters Energy)
• Technology - Hacker News, Ars Technica, The Verge, MIT Tech Review
• AI / ML - ArXiv, VentureBeat AI, The Verge AI, MIT Tech Review
• Finance - CNBC, MarketWatch, Financial Times, Yahoo Finance
• Government - White House, State Dept, Pentagon, Treasury, Fed, SEC, UN News, CISA
• Intel Feed - Defense One, Breaking Defense, Bellingcat, Krebs Security, Janes
• Think Tanks - Foreign Policy, Atlantic Council, Foreign Affairs, CSIS, RAND, Brookings, Carnegie
• Crisis Watch - International Crisis Group, IAEA, WHO, UNHCR
• Regional Sources - Xinhua, TASS, Kyiv Independent, Moscow Times
• Layoffs Tracker - Tech industry job cuts

Source Filtering

The 📡 SOURCES button in the header opens a global source management modal, enabling fine-grained control over which news sources appear in the dashboard.

Capabilities:

• Search: Filter the source list by name to quickly find specific outlets
• Individual Toggle: Click any source to enable/disable it
• Bulk Actions: "Select All" and "Select None" for quick adjustments
• Counter Display: Shows "45/77 enabled" to indicate current selection
• Persistence: Settings are saved to localStorage and persist across sessions

Use Cases:

• Noise Reduction: Disable high-volume aggregators (Google News) to focus on primary sources
• Regional Focus: Enable only sources relevant to a specific geographic area
• Source Quality: Disable sources with poor signal-to-noise ratio
• Bias Management: Balance coverage by enabling/disabling sources with known editorial perspectives

Technical Details:

• Disabled sources are filtered at fetch time (not display time), reducing bandwidth and API calls
• Affects all news panels simultaneously—disable BBC once, it's gone everywhere
• Panels with all sources disabled show "All sources disabled" message
• Changes take effect on the next refresh cycle

Regional Intelligence Panels

Dedicated panels provide focused coverage for strategically significant regions:

Each panel aggregates region-specific sources to provide concentrated situational awareness for that theater. This enables focused monitoring when global events warrant attention to a particular region.

Live News Streams

Embedded YouTube live streams from major news networks with channel switching:

Core Features:

• Channel Switcher - One-click switching between networks
• Live Indicator - Blinking dot shows stream status, click to pause/play
• Mute Toggle - Audio control (muted by default)
• Double-Width Panel - Larger video player for better viewing

Performance Optimizations:

The live stream panel uses the YouTube IFrame Player API rather than raw iframe embedding. This provides several advantages:

Idle Detection:

To conserve resources, the panel implements automatic idle pausing:

This prevents background tabs from consuming bandwidth while preserving user preference for manually-paused streams.

Market Data

• Stocks - Major indices and tech stocks via Finnhub (Yahoo Finance backup)
• Commodities - Oil, gold, natural gas, copper, VIX
• Crypto - Bitcoin, Ethereum, Solana via CoinGecko
• Sector Heatmap - Visual sector performance (11 SPDR sectors)
• Economic Indicators - Fed data via FRED (assets, rates, yields)
• Oil Analytics - EIA data: WTI/Brent prices, US production, US inventory with weekly changes
• Government Spending - USASpending.gov: Recent federal contracts and awards

Prediction Markets

• Polymarket integration for event probability tracking
• Correlation analysis with news events

Search (⌘K)

Universal search across all data sources:

• News articles
• Geographic hotspots and conflicts
• Infrastructure (pipelines, cables, datacenters)
• Nuclear facilities and irradiators
• Markets and predictions

Data Export

• CSV and JSON export of current dashboard state
• Historical playback from snapshots

Signal Intelligence

The dashboard continuously analyzes data streams to detect significant patterns and anomalies. Signals appear in the header badge (⚡) with confidence scores.

Intelligence Findings Badge

The header displays an Intelligence Findings badge that consolidates two types of alerts:

Interaction: Clicking the badge—or clicking an individual alert—opens a detail modal showing:

• Full alert description and context
• Component breakdown (for composite alerts)
• Affected countries or regions
• Confidence score and priority level
• Timestamp and trending direction

This provides a unified command center for all intelligence findings, whether generated by correlation analysis or module-specific threshold detection.

Signal Types

The system detects 12 distinct signal types across news, markets, military, and infrastructure domains:

News & Source Signals

Market Signals

Infrastructure & Energy Signals

Geopolitical & Military Signals

How It Works

The correlation engine maintains rolling snapshots of:

• News topic frequency (by keyword extraction)
• Market price changes
• Prediction market probabilities

Each refresh cycle compares current state to previous snapshot, applying thresholds and deduplication to avoid alert fatigue. Signals include confidence scores (60-95%) based on the strength of the pattern.

Entity-Aware Correlation

The signal engine uses a knowledge base of 100+ entities to intelligently correlate market movements with news coverage. Rather than simple keyword matching, the system understands that "AVGO" (the ticker) relates to "Broadcom" (the company), "AI chips" (the sector), and entities like "Nvidia" (a competitor).

Entity Knowledge Base

Each entity in the registry contains:

Entity Types

How Entity Matching Works

When a market moves significantly (≥2%), the system:

1. Looks up the ticker in the entity registry (e.g., AVGO → broadcom)
2. Gathers all identifiers: aliases, keywords, sector peers, related entities
3. Scans all news clusters for matches against any identifier
4. Scores confidence based on match type:
   • Alias match (exact name): 95%
   • Keyword match (topic): 70%
   • Related entity match: 60%

If correlated news is found → "Market Move Explained" signal with the news headline. If no correlation after exhaustive search → "Silent Divergence" signal.

Example: Broadcom +2.5%

1. Ticker AVGO detected with +2.5% move
2. Entity lookup: broadcom
3. Search terms: ["Broadcom", "AVGO", "AI chips", "semiconductors", "VMware", "nvidia", "intel", "amd"]
4. News scan finds: "Broadcom AI Revenue Beats Estimates"
5. Result: "✓ Market Move Explained: Broadcom AI Revenue Beats Estimates"

Without this system, the same move would generate a generic "Silent Divergence: AVGO +2.5%" signal.

Sector Coverage

The entity registry spans strategically significant sectors:

This broad coverage enables correlation detection across diverse geopolitical and market events.

Entity Registry Architecture

The entity registry is a knowledge base of 600+ entities with rich metadata for intelligent correlation:

{
  id: 'NVDA',           // Unique identifier
  name: 'Nvidia',       // Display name
  type: 'company',      // company | country | index | commodity | currency
  sector: 'semiconductors',
  searchTerms: ['Nvidia', 'NVDA', 'Jensen Huang', 'H100', 'CUDA'],
  aliases: ['nvidia', 'nvda'],
  competitors: ['AMD', 'INTC'],
  related: ['AVGO', 'TSM', 'ASML'],  // Related entities
  country: 'US',        // Headquarters/origin
}

Entity Types:

Lookup Indexes:

The registry provides multiple lookup paths for fast entity resolution:

Signal Deduplication

To prevent alert fatigue, signals use type-specific TTL (time-to-live) values for deduplication:

Market signals use symbol-only keys (e.g., silent_divergence:AVGO) rather than including the price change. This means a stock moving +2.5% then +3.0% won't trigger duplicate alerts—the first alert covers the story.

Source Intelligence

Not all sources are equal. The system implements a dual classification to prioritize authoritative information.

Source Tiers (Authority Ranking)

When multiple sources report the same story, the lowest tier (most authoritative) source is displayed as the primary, with others listed as corroborating.

Source Types (Categorical)

Sources are also categorized by function for triangulation detection:

• Wire - News agencies (Reuters, AP, AFP, Bloomberg)
• Gov - Official government (White House, Pentagon, State Dept, Fed, SEC)
• Intel - Defense/security specialists (Defense One, Bellingcat, Krebs)
• Mainstream - Major news outlets (BBC, Guardian, NPR, Al Jazeera)
• Market - Financial press (CNBC, MarketWatch, Financial Times)
• Tech - Technology coverage (Hacker News, Ars Technica, MIT Tech Review)

Propaganda Risk Indicators

The dashboard visually flags sources with known state affiliations or propaganda risk, enabling users to appropriately weight information from these outlets.

Risk Levels

Flagged Sources

Display Locations

Propaganda risk badges appear in:

• Cluster primary source: Badge next to the main source name
• Top sources list: Small badge next to each flagged source
• Cluster view: Visible when expanding multi-source clusters

Why Include State Media?

State-controlled outlets are included rather than filtered because:

1. Signal Value: What state media reports (and omits) reveals government priorities
2. Rapid Response: State media often breaks domestic news faster than international outlets
3. Narrative Analysis: Understanding how events are framed by different governments
4. Completeness: Excluding them creates blind spots in coverage

The badges ensure users can contextualize state media reports rather than unknowingly treating them as independent journalism.

Entity Extraction System

The dashboard extracts named entities (companies, countries, leaders, organizations) from news headlines to enable news-to-market correlation and entity-based filtering.

How It Works

Headlines are scanned against a curated entity index containing:

Entity Matching

Each entity has multiple match patterns for comprehensive detection:

Entity: NVIDIA (NVDA)
  Aliases: nvidia, nvda, jensen huang
  Keywords: gpu, h100, a100, cuda, ai chip
  Match Types:
    - Name match: "NVIDIA announces..." → 95% confidence
    - Alias match: "Jensen Huang says..." → 90% confidence
    - Keyword match: "H100 shortage..." → 70% confidence

Confidence Scoring

Entity extraction produces confidence scores based on match quality:

Market Correlation

When a market symbol moves significantly, the system searches news clusters for related entities:

1. Symbol lookup - Find entity by market symbol (e.g., AAPL → Apple)
2. News search - Find clusters mentioning the entity or related entities
3. Confidence ranking - Sort by extraction confidence
4. Result - "Market Move Explained" or "Silent Divergence" signal

This enables signals like:

• Explained: "AVGO +5.2% — Broadcom mentioned in 3 news clusters (AI chip demand)"
• Silent: "AVGO +5.2% — No correlated news after entity search"

Signal Context ("Why It Matters")

Every signal includes contextual information explaining its analytical significance:

Context Fields

Signal-Specific Context

This contextual layer transforms raw alerts into actionable intelligence by explaining the analytical reasoning behind each signal.

Algorithms & Design

News Clustering

Related articles are grouped using Jaccard similarity on tokenized headlines:

similarity(A, B) = |A ∩ B| / |A ∪ B|

Tokenization:

• Headlines are lowercased and split on word boundaries
• Stop words removed: "the", "a", "an", "in", "on", "at", "to", "for", "of", "and", "or"
• Short tokens (<3 characters) filtered out
• Result cached per headline for performance

Inverted Index Optimization: Rather than O(n²) pairwise comparison, the algorithm uses an inverted index:

1. Build token → article indices map
2. For each article, find candidate matches via shared tokens
3. Only compute Jaccard for candidates with token overlap
4. This reduces comparisons from ~10,000 to ~500 for typical news loads

Clustering Rules:

• Articles with similarity ≥ 0.5 are grouped into clusters
• Clusters are sorted by source tier, then recency
• The most authoritative source becomes the "primary" headline
• Clusters maintain full item list for multi-source attribution

Velocity Analysis

Each news cluster tracks publication velocity:

• Sources per hour = article count / time span
• Trend = rising/stable/falling based on first-half vs second-half publication rate
• Levels: Normal (<3/hr), Elevated (3-6/hr), Spike (>6/hr)

Sentiment Detection

Headlines are scored against curated word lists:

Negative indicators: war, attack, killed, crisis, crash, collapse, threat, sanctions, invasion, missile, terror, assassination, recession, layoffs...

Positive indicators: peace, deal, agreement, breakthrough, recovery, growth, ceasefire, treaty, alliance, victory...

Score determines sentiment classification: negative (<-1), neutral (-1 to +1), positive (>+1)

Entity Extraction

News headlines are scanned against the entity knowledge base using word-boundary regex matching:

regex = /\b{escaped_alias}\b/gi

Index Structure: The entity index pre-builds five lookup maps for O(1) access:

Matching Algorithm:

1. Alias matching (highest confidence):

   • Iterate all aliases (minimum 3 characters to avoid false positives)
   • Word-boundary regex prevents partial matches ("AI" won't match "RAID")
   • First alias match for each entity stops further searching (deduplication)

2. Keyword matching (medium confidence):

   • Simple substring check (faster than regex)
   • Multiple entities may match same keyword
   • Lower confidence (70%) than alias matches (95%)

3. Related entity expansion:

   • If entity has related field, those entities are also checked
   • Example: AVGO move also searches for NVDA, INTC, AMD news

Performance:

• Index builds once on first access (cached singleton)
• Alias map has ~300 entries for 100+ entities
• Keyword map has ~400 entries
• Full news scan: O(aliases × clusters) ≈ 300 × 50 = 15,000 comparisons

Baseline Deviation (Z-Score)

The system maintains rolling baselines for news volume per topic:

• 7-day average and 30-day average stored in IndexedDB
• Standard deviation calculated from historical counts
• Z-score = (current - mean) / stddev

Deviation levels:

• Spike: Z > 2.5 (statistically rare increase)
• Elevated: Z > 1.5
• Normal: -2 < Z < 1.5
• Quiet: Z < -2 (unusually low activity)

This enables detection of anomalous activity even when absolute numbers seem normal.

Dynamic Hotspot Activity

Hotspots on the map are not static threat levels. Activity is calculated in real-time based on news correlation.

Each hotspot defines keywords:

{
  id: 'dc',
  name: 'DC',
  keywords: ['pentagon', 'white house', 'congress', 'cia', 'nsa', ...],
  agencies: ['Pentagon', 'CIA', 'NSA', 'State Dept'],
}

The system counts matching news articles in the current feed, applies velocity analysis, and assigns activity levels:

This creates a dynamic "heat map" of global attention based on live news flow.

Hotspot Escalation Signals

Beyond visual activity levels, the system generates escalation signals when hotspots show significant changes across multiple dimensions. This multi-component approach reduces false positives by requiring corroboration from independent data streams.

Escalation Components

Each hotspot's escalation score blends four weighted components:

Score Calculation

static_baseline = hotspot.baselineRisk  // 1-5 per hotspot
dynamic_score = (
  news_component × 0.35 +
  cii_component × 0.25 +
  geo_component × 0.25 +
  military_component × 0.15
)
proximity_boost = hotspot_proximity_multiplier  // 1.0-2.0

final_score = (static_baseline × 0.30 + dynamic_score × 0.70) × proximity_boost

Trend Detection

The system maintains 48-point history (24 hours at 30-minute intervals) per hotspot:

• Linear regression calculates slope of recent scores
• Rising: Slope > +0.1 points per interval
• Falling: Slope < -0.1 points per interval
• Stable: Slope within ±0.1

Signal Generation

Escalation signals (hotspot_escalation) are emitted when:

1. Final score exceeds threshold (typically 60)
2. At least 2 hours since last signal for this hotspot (cooldown)
3. Trend is rising or score is critical (>80)

Signal Context

This multi-signal approach means a hotspot escalation signal represents corroborated evidence across independent data streams—not just a spike in news mentions.

Regional Focus Navigation

The FOCUS selector in the header provides instant navigation to strategic regions. Each preset is calibrated to center on the region's geographic area with an appropriate zoom level.

Available Regions

Quick Navigation

The FOCUS dropdown enables rapid context switching:

1. Breaking news - Jump to the affected region
2. Regional briefing - Cycle through regions for situational awareness
3. Crisis monitoring - Lock onto a specific theater

Regional views are encoded in shareable URLs, enabling direct links to specific geographic contexts.

Map Pinning

By default, the map scrolls with the page, allowing you to scroll down to view panels below. The pin button (📌) in the map header toggles sticky behavior:

When to Pin

• Active monitoring - Keep the map visible while reading news panels
• Cross-referencing - Compare map markers with panel data
• Presentation - Show the map while discussing panel content

When to Unpin

• Panel focus - Read through panels without map taking screen space
• Mobile - Pin is disabled on mobile for better space utilization
• Research - Focus on data panels without geographic distraction

Pin state persists across sessions via localStorage.

Country Instability Index (CII)

The dashboard maintains a real-time instability score for 20 strategically significant countries. Rather than relying on static risk ratings, the CII dynamically reflects current conditions based on multiple input streams.

Monitored Countries (Tier 1)

Three Component Scores

Each country's CII is computed from three weighted components:

Scoring Algorithm

Unrest Score:
  base = min(50, protest_count × 8)
  fatality_boost = min(30, total_fatalities × 5)
  severity_boost = min(20, high_severity_count × 10)
  unrest = min(100, base + fatality_boost + severity_boost)

Security Score:
  flight_score = min(50, military_flights × 3)
  vessel_score = min(30, naval_vessels × 5)
  security = min(100, flight_score + vessel_score)

Information Score:
  base = min(40, news_count × 5)
  velocity_boost = min(40, avg_velocity × 10)
  alert_boost = 20 if any_alert else 0
  information = min(100, base + velocity_boost + alert_boost)

Final CII = round(unrest × 0.4 + security × 0.3 + information × 0.3)

Scoring Bias Prevention

Raw news volume creates a natural bias—English-language media generates far more coverage of the US, UK, and Western Europe than conflict zones. Without correction, stable democracies would consistently score higher than actual crisis regions.

Log Scaling for High-Volume Countries

Countries with high media coverage receive logarithmic dampening on their unrest and information scores:

if (newsVolume > threshold):
  dampingFactor = 1 / (1 + log10(newsVolume / threshold))
  score = rawScore × dampingFactor

This ensures the US receiving 50 news mentions about routine political activity doesn't outscore Ukraine with 10 mentions about active combat.

Conflict Zone Floor Scores

Active conflict zones have minimum score floors that prevent them from appearing stable during data gaps or low-coverage periods:

The floor applies after the standard calculation—if the computed score exceeds the floor, the computed score is used. This prevents false "all clear" signals while preserving sensitivity to actual escalations.

Instability Levels

Trend Detection

The CII tracks 24-hour changes to identify trajectory:

• Rising: Score increased by ≥5 points (escalating situation)
• Stable: Change within ±5 points (steady state)
• Falling: Score decreased by ≥5 points (de-escalation)

Contextual Score Boosts

Beyond the base component scores, several contextual factors can boost a country's CII score (up to a combined maximum of 23 additional points):

Hotspot Boost Calculation:

• Hotspot activity (0-100) scaled by 1.5× then capped at 10
• Zero boost for countries with no associated hotspot activity

News Urgency Boost Tiers:

• Information ≥70: +5 points
• Information ≥50: +3 points
• Information <50: +0 points

Focal Point Boost Tiers:

• Critical urgency: +8 points
• Elevated urgency: +4 points
• Normal urgency: +0 points

These boosts are designed to elevate scores only when corroborating evidence exists—a country must have both high base scores AND contextual signals to reach extreme levels.

Server-Side Pre-Computation

To eliminate the "cold start" problem where new users would see blank data during the Learning Mode warmup, CII scores are pre-computed server-side via the /api/risk-scores endpoint. See the Server-Side Risk Score API section for details.

Learning Mode (15-Minute Warmup)

On dashboard startup, the CII system enters Learning Mode—a 15-minute calibration period where scores are calculated but alerts are suppressed. This prevents the flood of false-positive alerts that would otherwise occur as the system establishes baseline values.

Note: Server-side pre-computation now provides immediate scores to new users—Learning Mode primarily affects client-side dynamic adjustments and alert generation rather than initial score display.

Why 15 minutes? Real-world testing showed that CII scores stabilize after approximately 10-20 minutes of data collection. The 15-minute window provides sufficient time for:

• Multiple refresh cycles across all data sources
• Trend detection to establish direction (rising/stable/falling)
• Cross-source correlation to normalize bias

Visual Indicators

During Learning Mode, the dashboard provides clear visual feedback:

Behavior

Minutes 0-15: Learning Mode Active
  - CII scores calculated and displayed (dimmed)
  - Trend detection active (stores baseline)
  - All CII-related alerts suppressed
  - Progress bar fills as time elapses

After 15 minutes: Learning Complete
  - Full opacity scores
  - Alert generation enabled (threshold ≥10 point change)
  - "All data sources active" status shown

This ensures users understand that early scores are provisional while preventing alert fatigue during the calibration period.

Keyword Attribution

Countries are matched to data via keyword lists:

• Russia: russia, moscow, kremlin, putin
• China: china, beijing, xi jinping, prc
• Taiwan: taiwan, taipei

This enables attribution of news and events to specific countries even when formal country codes aren't present in the source data.

Geographic Convergence Detection

One of the most valuable intelligence signals is when multiple independent data streams converge on the same geographic area. This often precedes significant events.

How It Works

The system maintains a real-time grid of geographic cells (1° × 1° resolution). Each cell tracks four event types:

When 3 or more different event types occur within the same cell during a 24-hour window, a convergence alert is generated.

Convergence Scoring

type_score = event_types × 25      # Max 100 (4 types)
count_boost = min(25, total_events × 2)
convergence_score = min(100, type_score + count_boost)

Alert Thresholds

Example Scenarios

Taiwan Strait Buildup

• Cell: 25°N, 121°E
• Events: Military flights (3), Naval vessels (2), Protests (1)
• Score: 75 + 12 = 87 (Critical)
• Signal: "Geographic Convergence (3 types) - military flights, naval vessels, protests"

Middle East Flashpoint

• Cell: 32°N, 35°E
• Events: Military flights (5), Protests (8), Earthquake (1)
• Score: 75 + 25 = 100 (Critical)
• Signal: Multiple activity streams converging on region

Why This Matters

Individual data points are often noise. But when protests break out, military assets reposition, and seismic monitors detect anomalies in the same location simultaneously, it warrants attention—regardless of whether any single source is reporting a crisis.

Infrastructure Cascade Analysis

Critical infrastructure is interdependent. A cable cut doesn't just affect connectivity—it creates cascading effects across dependent countries and systems. The cascade analysis system visualizes these dependencies.

Dependency Graph

The system builds a graph of 279 infrastructure nodes and 280 dependency edges:

Cascade Calculation

When a user selects an infrastructure asset for analysis, a breadth-first cascade propagates through the graph:

1. Start at source node (e.g., "cable:marea")
2. For each dependent node:
   impact = edge_strength × disruption_level × (1 - redundancy)
3. Categorize impact:
   - Critical: impact > 0.8
   - High: impact > 0.5
   - Medium: impact > 0.2
   - Low: impact ≤ 0.2
4. Recurse to depth 3 (prevent infinite loops)

Redundancy Modeling

The system accounts for alternative routes:

• Cables with high redundancy show reduced impact
• Countries with multiple cable landings show lower vulnerability
• Alternative routes are displayed with capacity percentages

Example Analysis

MAREA Cable Disruption:

Source: MAREA (US ↔ Spain, 200 Tbps)
Countries Affected: 4
- Spain: Medium (redundancy via other Atlantic cables)
- Portugal: Low (secondary landing)
- France: Low (alternative routes via UK)
- US: Low (high redundancy)
Alternative Routes: TAT-14 (35%), Hibernia (22%), AEConnect (18%)

FLAG Europe-Asia Disruption:

Source: FLAG Europe-Asia (UK ↔ Japan)
Countries Affected: 7
- India: Medium (major capacity share)
- UAE, Saudi Arabia: Medium (limited alternatives)
- UK, Japan: Low (high redundancy)
Alternative Routes: SEA-ME-WE 6 (11%), 2Africa (8%), Falcon (8%)

Use Cases

• Pre-positioning: Understand which countries are most vulnerable to specific infrastructure failures
• Risk Assessment: Evaluate supply chain exposure to chokepoint disruptions
• Incident Response: Quickly identify downstream effects of reported cable cuts or pipeline damage

Undersea Cable Activity Monitoring

The dashboard monitors real-time cable operations and advisories from official maritime warning systems, providing early warning of potential connectivity disruptions.

Data Sources

How It Works

The system parses NGA (National Geospatial-Intelligence Agency) maritime warnings for cable-related activity:

1. Keyword filtering: Warnings containing "CABLE", "CABLESHIP", "SUBMARINE CABLE", "FIBER OPTIC" are extracted
2. Coordinate parsing: DMS and decimal coordinates are extracted from warning text
3. Cable matching: Coordinates are matched to nearest cable routes within 5° radius
4. Severity classification: Keywords like "FAULT", "BREAK", "DAMAGE" indicate faults; others indicate maintenance

Alert Types

Repair Ship Tracking

When a cableship is mentioned in warnings, the system extracts:

• Vessel name: CS Reliance, Cable Innovator, etc.
• Status: "En route" or "On station"
• Location: Current working area
• Associated cable: Nearest cable route

This enables monitoring of ongoing repair operations before official carrier announcements.

Why This Matters

Undersea cables carry 95% of intercontinental data traffic. A cable cut can:

• Cause regional internet outages
• Disrupt financial transactions
• Impact military communications
• Create economic cascading effects

Early visibility into cable operations—even maintenance windows—provides advance warning for contingency planning.

Strategic Risk Overview

The Strategic Risk Overview provides a composite dashboard that synthesizes all intelligence modules into a single risk assessment.

Composite Score (0-100)

The strategic risk score combines three components:

Risk Levels

Unified Alert System

Alerts from all modules are merged using temporal and spatial deduplication:

• Time window: Alerts within 2 hours may be merged
• Distance threshold: Alerts within 200km may be merged
• Same country: Alerts affecting the same country may be merged

When alerts merge, they become composite alerts that show the full picture:

Type: Composite Alert
Title: Convergence + CII + Infrastructure: Ukraine
Components:
  - Geographic Convergence: 4 event types in Kyiv region
  - CII Spike: Ukraine +15 points (Critical)
  - Infrastructure: Black Sea cables at risk
Priority: Critical

Alert Priority

Trend Detection

The system tracks the composite score over time:

• First measurement establishes baseline (shows "Stable")
• Subsequent changes of ±5 points trigger trend changes
• This prevents false "escalating" signals on initialization

Pentagon Pizza Index (PizzINT)

The dashboard integrates real-time foot traffic data from strategic locations near government and military facilities. This "Pizza Index" concept—tracking late-night activity spikes at restaurants near the Pentagon, Langley, and other facilities—provides an unconventional indicator of crisis activity.

How It Works

The system aggregates percentage-of-usual metrics from monitored locations:

1. Locations: Fast food, pizza shops, and convenience stores near Pentagon, CIA, NSA, State Dept, and other facilities
2. Aggregation: Activity percentages are averaged, capped at 100%
3. Spike Detection: Locations exceeding their baseline are flagged

DEFCON-Style Alerting

Aggregate activity maps to a 5-level readiness scale:

GDELT Tension Pairs

The indicator also displays geopolitical tension scores from GDELT (Global Database of Events, Language, and Tone):

Each pair shows:

• Current tension score (GDELT's normalized metric)
• 7-day trend (rising, falling, stable)
• Percentage change from previous period

This provides context for the activity levels—a spike at Pentagon locations during a rising China-Taiwan tension score carries different weight than during a quiet period.

Related Assets

News clusters are automatically enriched with nearby critical infrastructure. When a story mentions a geographic region, the system identifies relevant assets within 600km, providing immediate operational context.

Asset Types

Location Inference

The system infers the geographic focus of news stories through:

1. Keyword matching: Headlines are scanned against hotspot keyword lists (e.g., "Taiwan" → Taiwan Strait hotspot)
2. Confidence scoring: Multiple keyword matches increase location confidence
3. Fallback to conflicts: If no hotspot matches, active conflict zones are checked

Distance Calculation

Assets are ranked by Haversine distance from the inferred location:

d = 2r × arcsin(√(sin²(Δφ/2) + cos(φ₁) × cos(φ₂) × sin²(Δλ/2)))

Up to 3 assets per type are displayed, sorted by proximity.

Example Context

A news cluster about "pipeline explosion in Germany" would show:

• Pipelines: Nord Stream (23km), Yamal-Europe (156km)
• Cables: TAT-14 landing (89km)
• Bases: Ramstein (234km)

Clicking an asset zooms the map to its location and displays detailed information.

Custom Monitors

Create personalized keyword alerts that scan all incoming news:

1. Enter comma-separated keywords (e.g., "nvidia, gpu, chip shortage")
2. System assigns a unique color
3. Matching articles are highlighted in the Monitor panel
4. Matching articles in clusters inherit the monitor color

Monitors persist across sessions via LocalStorage.

Activity Tracking

The dashboard highlights newly-arrived items so you can quickly identify what changed since your last look.

Visual Indicators

Automatic "Seen" Detection

The system uses IntersectionObserver to detect when panels become visible:

• When a panel is >50% visible for >500ms, items are marked as "seen"
• Scrolling through a panel marks visible items progressively
• Switching panels resets the "new" state appropriately

Panel-Specific Tracking

Each panel maintains independent activity state:

• News: New clusters since last view
• Markets: Price changes exceeding thresholds
• Predictions: Probability shifts >5%
• Natural Events: New earthquakes and EONET events

This enables focused monitoring—you can collapse panels you've reviewed and see at a glance which have new activity.

Snapshot System

The dashboard captures periodic snapshots for historical analysis:

• Automatic capture every refresh cycle
• 7-day retention with automatic cleanup
• Stored data: news clusters, market prices, prediction values, hotspot levels
• Playback: Load historical snapshots to see past dashboard states

Baselines (7-day and 30-day averages) are stored in IndexedDB for deviation analysis.

Maritime Intelligence

The Ships layer provides real-time vessel tracking and maritime domain awareness through AIS (Automatic Identification System) data.

Chokepoint Monitoring

The system monitors eight critical maritime chokepoints where disruptions could impact global trade:

Density Analysis

Vessel positions are aggregated into a 2° grid to calculate traffic density. Each cell tracks:

• Current vessel count
• Historical baseline (30-minute rolling window)
• Change percentage from baseline

Density changes of ±30% trigger alerts, indicating potential congestion, diversions, or blockades.

Dark Ship Detection

The system monitors for AIS gaps—vessels that stop transmitting their position. An AIS gap exceeding 60 minutes in monitored regions may indicate:

• Sanctions evasion (ship-to-ship transfers)
• Illegal fishing
• Military activity
• Equipment failure

Vessels reappearing after gaps are flagged for the duration of the session.

WebSocket Architecture

AIS data flows through a WebSocket relay for real-time updates without polling:

AISStream → WebSocket Relay → Browser
              (ws://relay)

The connection automatically reconnects on disconnection with a 30-second backoff. When the Ships layer is disabled, the WebSocket disconnects to conserve resources.

Railway Relay Architecture

Some APIs block requests from cloud providers (Vercel, AWS, Cloudflare Workers). A Railway relay server provides authenticated access:

Browser → Railway Relay → External APIs
           (Node.js)      (AIS, OpenSky, RSS)

Relay Functions:

Environment Variables (Railway):

• AISSTREAM_API_KEY - AIS data access
• OPENSKY_CLIENT_ID - OAuth2 client ID
• OPENSKY_CLIENT_SECRET - OAuth2 client secret

Why Railway?

• Residential IP ranges (not blocked like cloud providers)
• WebSocket support for persistent connections
• Global edge deployment for low latency
• Free tier sufficient for moderate traffic

The relay is stateless—it simply authenticates and proxies requests. All caching and processing happens client-side or in Vercel Edge Functions.

Military Tracking

The Military layer provides specialized tracking of military vessels and aircraft, identifying assets by their transponder characteristics and monitoring activity patterns.

Military Vessel Identification

Vessels are identified as military through multiple methods:

MMSI Analysis: Maritime Mobile Service Identity numbers encode the vessel's flag state. The system maintains a mapping of 150+ country codes to identify naval vessels:

Known Vessel Database: A curated database of 50+ named vessels enables positive identification when AIS transmits vessel names:

Vessel Classification Algorithm:

1. Check vessel name against known database (hull numbers and ship names)
2. Fall back to AIS ship type code if name match fails
3. Apply MMSI pattern matching for country/operator identification
4. For naval-prefix vessels (USS, HMS, HMCS, HMAS, INS, JS, ROKS, TCG), infer military status

Callsign Patterns: Known military callsign prefixes (NAVY, GUARD, etc.) provide secondary identification.

Naval Chokepoint Monitoring

The system monitors 12 critical maritime chokepoints with configurable detection radii:

When military vessels enter these zones, proximity alerts are generated.

Naval Base Proximity

Activity near 12 major naval installations is tracked:

• Norfolk (USA) - Atlantic Fleet headquarters
• Pearl Harbor (USA) - Pacific Fleet base
• Sevastopol (Russia) - Black Sea Fleet
• Qingdao (China) - North Sea Fleet
• Yokosuka (Japan) - US 7th Fleet

Vessels within 50km of these bases are flagged, enabling detection of unusual activity patterns.

Aircraft Tracking (OpenSky)

Military aircraft are tracked via the OpenSky Network using ADS-B data. OpenSky blocks unauthenticated requests from cloud provider IPs (Vercel, Railway, AWS), so aircraft tracking requires a relay server with credentials.

Authentication:

• Register for a free account at opensky-network.org
• Create an API client in account settings to get OPENSKY_CLIENT_ID and OPENSKY_CLIENT_SECRET
• The relay uses OAuth2 client credentials flow to obtain Bearer tokens
• Tokens are cached (30-minute expiry) and automatically refreshed

Identification Methods:

• Callsign matching: Known military callsign patterns (RCH, REACH, DUKE, etc.)
• ICAO hex ranges: Military aircraft use assigned hex code blocks by country
• Altitude/speed profiles: Unusual flight characteristics

Tracked Metrics:

• Position history (20-point trails over 5-minute windows)
• Altitude and ground speed
• Heading and track

Activity Detection:

• Formations (multiple military aircraft in proximity)
• Unusual patterns (holding, reconnaissance orbits)
• Chokepoint transits

Vessel Position History

The system maintains position trails for tracked vessels:

• 30-point history per MMSI
• 10-minute cleanup interval for stale data
• Trail visualization on map for recent movement

This enables detection of loitering, circling, or other anomalous behavior patterns.

Military Surge Detection

The system continuously monitors military aircraft activity to detect surge events—significant increases above normal operational baselines that may indicate mobilization, exercises, or crisis response.

Theater Classification

Military activity is analyzed across five geographic theaters:

Aircraft Classification

Aircraft are categorized by callsign pattern matching:

Baseline Calculation

The system maintains rolling 48-hour activity baselines per theater:

• Minimum 6 data samples required for reliable baseline
• Default baselines when data insufficient: 3 transport, 2 fighter, 1 reconnaissance
• Activity below 50% of baseline indicates stand-down

Surge Detection Algorithm

surge_ratio = current_count / baseline
surge_triggered = (
  ratio ≥ 2.0 AND
  transport ≥ 5 AND
  fighters ≥ 4
)

Surge Signal Output

When a surge is detected, the system generates a military_surge signal:

Foreign Military Presence Detection

Beyond surge detection, the system monitors for foreign military aircraft in sensitive regions—situations where aircraft from one nation appear in geopolitically significant areas outside their normal operating range.

Sensitive Regions

The system tracks 18 strategically significant geographic areas:

Detection Logic

For each sensitive region, the system:

1. Identifies all military aircraft within the region boundary
2. Groups aircraft by operating nation
3. Excludes "home region" operators (e.g., Russian VKS in Baltic excluded from alert)
4. Applies concentration thresholds (typically 2-3 aircraft per operator)

Critical Combinations

Certain operator-region combinations trigger critical severity alerts:

Signal Output

Foreign presence detection generates a foreign_military_presence signal:

Aircraft Enrichment

Military aircraft tracking is enhanced with Wingbits enrichment data, providing detailed aircraft information that goes beyond basic transponder data.

What Wingbits Provides

When an aircraft is detected via OpenSky ADS-B, the system queries Wingbits for:

Military Classification Algorithm

The enrichment service analyzes owner and operator fields against curated keyword lists:

Confirmed Military (owner/operator match):

• Government: "United States Air Force", "Department of Defense", "Royal Air Force"
• International: "NATO", "Ministry of Defence", "Bundeswehr"

Likely Military (operator ICAO codes):

• AIO (Air Mobility Command), RRR (Royal Air Force), GAF (German Air Force)
• RCH (REACH flights), CNV (Convoy flights), DOD (Department of Defense)

Possible Military (defense contractors):

• Northrop Grumman, Lockheed Martin, General Atomics, Raytheon, Boeing Defense, L3Harris

Aircraft Type Matching:

• Transport: C-17, C-130, C-5, KC-135, KC-46
• Reconnaissance: RC-135, U-2, RQ-4, E-3, E-8
• Combat: F-15, F-16, F-22, F-35, B-52, B-2
• European: Eurofighter, Typhoon, Rafale, Tornado, Gripen

Confidence Levels

Each enriched aircraft receives a confidence classification:

Caching Strategy

Aircraft details rarely change, so aggressive caching reduces API load:

• Server-side: HTTP Cache-Control headers (24-hour max-age)
• Client-side: 1-hour local cache per aircraft
• Batch optimization: Up to 20 aircraft per API call

This means an aircraft's details are fetched at most once per day, regardless of how many times it appears on the map.

Space Launch Infrastructure

The Spaceports layer displays global launch facilities for monitoring space-related activity and supply chain implications.

Tracked Launch Sites

Why This Matters

Space launches are geopolitically significant:

• Military implications: Many launches are dual-use (civilian/military)
• Technology competition: Launch cadence indicates space program advancement
• Supply chain: Satellite services affect communications, GPS, reconnaissance
• Incident correlation: News about space debris, failed launches, or policy changes

Critical Mineral Deposits

The Minerals layer displays strategic mineral extraction sites essential for modern technology and defense supply chains.

Tracked Resources

Key Sites

Supply Chain Risks

Critical minerals are geopolitically concentrated:

• Cobalt: 70% from DRC, significant artisanal mining concerns
• Rare Earths: 60% from China, processing nearly monopolized
• Lithium: Expanding production but demand outpacing supply

News about these regions or mining companies can signal supply disruptions affecting technology and defense sectors.

Cyber Threat Actors (APT Groups)

The map displays geographic attribution markers for major state-sponsored Advanced Persistent Threat (APT) groups. These markers show the approximate operational centers of known threat actors.

Tracked Groups

Why This Matters

Cyber operations often correlate with geopolitical tensions. When news reports reference Russian cyber activity during a Ukraine escalation, or Iranian hacking during Middle East tensions, these markers provide geographic context for the threat landscape.

Visual Indicators

APT markers appear as warning triangles (⚠) with distinct styling. Clicking a marker shows:

• Official designation and common aliases
• State sponsor and intelligence agency
• Primary targeting sectors

Social Unrest Tracking

The Protests layer aggregates civil unrest data from two independent sources, providing corroboration and global coverage.

ACLED (Armed Conflict Location & Event Data)

Academic-grade conflict data with human-verified events:

• Coverage: Global, 30-day rolling window
• Event types: Protests, riots, strikes, demonstrations
• Metadata: Actors involved, fatalities, detailed notes
• Confidence: High (human-curated)

GDELT (Global Database of Events, Language, and Tone)

Real-time news-derived event data:

• Coverage: Global, 7-day rolling window
• Event types: Geocoded protest mentions from news
• Volume: Reports per location (signal strength)
• Confidence: Medium (algorithmic extraction)

Multi-Source Corroboration

Events from both sources are deduplicated using a 0.5° spatial grid and date matching. When both ACLED and GDELT report events in the same area:

• Confidence is elevated to "high"
• ACLED data takes precedence (higher accuracy)
• Source list shows corroboration

Severity Classification

Events near intelligence hotspots are cross-referenced to provide geopolitical context.

Map Display Filtering

To reduce visual clutter and focus attention on significant events, the map displays only high-severity protests and riots:

Lower-severity events are still tracked for CII scoring and data exports—they simply don't create map markers. This filtering prevents dense urban areas (which naturally generate more low-severity demonstrations) from overwhelming the map display.

Aviation Monitoring

The Flights layer tracks airport delays and ground stops at major US airports using FAA NASSTATUS data.

Delay Types

Severity Thresholds

Monitored Airports

The 30 largest US airports are tracked:

• Major hubs: JFK, LAX, ORD, ATL, DFW, DEN, SFO
• International gateways with high traffic volume
• Airports frequently affected by weather or congestion

Ground stops are particularly significant—they indicate severe disruption (weather, security, or infrastructure failure) and can cascade across the network.

Security & Input Validation

The dashboard handles untrusted data from dozens of external sources. Defense-in-depth measures prevent injection attacks and API abuse.

XSS Prevention

All user-visible content is sanitized before DOM insertion:

escapeHtml(str)  // Encodes & < > " ' as HTML entities
sanitizeUrl(url) // Allows only http/https protocols

This applies to:

• News headlines and sources (RSS feeds)
• Search results and highlights
• Monitor keywords (user input)
• Map popup content
• Tension pair labels

The <mark> highlighting in search escapes text before wrapping matches, preventing injection via crafted search queries.

Proxy Endpoint Validation

Serverless proxy functions validate and clamp all parameters:

This prevents upstream API abuse and rate limit exhaustion from malformed requests.

Content Security

• URLs are validated via URL() constructor—only http: and https: protocols are permitted
• External links use rel="noopener" to prevent reverse tabnapping
• No inline scripts or eval()—all code is bundled at build time

Fault Tolerance

External APIs are unreliable. Rate limits, outages, and network errors are inevitable. The system implements circuit breaker patterns to maintain availability.

Circuit Breaker Pattern

Each external service is wrapped in a circuit breaker that tracks failures:

Normal → Failure #1 → Failure #2 → OPEN (cooldown)
                                      ↓
                              5 minutes pass
                                      ↓
                                   CLOSED

Behavior during cooldown:

• New requests return cached data (if available)
• UI shows "temporarily unavailable" status
• No API calls are made (prevents hammering)

Protected Services

RSS feeds use per-feed circuit breakers—one failing feed doesn't affect others.

Graceful Degradation

When a service enters cooldown:

1. Cached data continues to display (stale but available)
2. Status panel shows service health
3. Automatic recovery when cooldown expires
4. No user intervention required

System Health Monitoring

The status panel (accessed via the health indicator in the header) provides real-time visibility into data source status and system health.

Health Indicator

The header displays a system health badge:

Click the indicator to expand the full status panel.

Data Source Status

The status panel lists all data feeds with their current state:

Per-Feed Information

Each feed entry shows:

• Source name - The data provider
• Last update - Time since last successful fetch
• Next refresh - Countdown to next scheduled fetch
• Cooldown remaining - Time until circuit breaker resets (if in cooldown)

Why This Matters

External APIs are unreliable. The status panel helps you understand:

• Data freshness - Is the news feed current or stale?
• Coverage gaps - Which sources are currently unavailable?
• Recovery timeline - When will failed sources retry?

This transparency enables informed interpretation of the dashboard data.

Data Freshness Tracking

Beyond simple "online/offline" status, the system tracks fine-grained freshness for each data source to indicate data reliability and staleness.

Freshness Levels

Source-Specific Thresholds

Each data source has calibrated freshness expectations:

Visual Indicators

The status panel displays freshness for each source:

• Colored dot indicates freshness level
• Time since update shows exact staleness
• Next refresh countdown shows when data will update

Why This Matters

Understanding data freshness is critical for decision-making:

• A "fresh" earthquake feed means recent events are displayed
• A "stale" news feed means you may be missing breaking stories
• A "critical" AIS stream means vessel positions are unreliable

This visibility enables appropriate confidence calibration when interpreting the dashboard.

Core vs. Optional Sources

Data sources are classified by their importance to risk assessment:

The Strategic Risk Overview panel adapts its display based on core source availability:

Freshness-Aware Risk Assessment

The composite risk score is adjusted based on data freshness:

If core sources fresh:
  → Full confidence in risk score
  → "All data sources active" indicator

If core sources stale:
  → Display warning: "Limited Data - [active sources]"
  → Score shown but flagged as potentially unreliable

If core sources unavailable:
  → "Insufficient data for risk assessment"
  → No score displayed

This prevents false "all clear" signals when the system actually lacks data to make that determination.

Conditional Data Loading

API calls are expensive. The system only fetches data for enabled layers, reducing unnecessary network traffic and rate limit consumption.

Layer-Aware Loading

When a layer is toggled OFF:

• No API calls for that data source
• No refresh interval scheduled
• WebSocket connections closed (for AIS)

When a layer is toggled ON:

• Data is fetched immediately
• Refresh interval begins
• Loading indicator shown on toggle button

Unconfigured Services

Some data sources require API keys (AIS relay, Cloudflare Radar). If credentials are not configured:

• The layer toggle is hidden entirely
• No failed requests pollute the console
• Users see only functional layers

This prevents confusion when deploying without full API access.

Performance Optimizations

The dashboard processes thousands of data points in real-time. Several techniques keep the UI responsive even with heavy data loads.

Web Worker for Analysis

CPU-intensive operations run in a dedicated Web Worker to avoid blocking the main thread:

The worker manager implements:

• Lazy initialization: Worker spawns on first use
• 10-second ready timeout: Rejects if worker fails to initialize
• 30-second request timeout: Prevents hanging on stuck operations
• Automatic cleanup: Terminates worker on fatal errors

Virtual Scrolling

Large lists (100+ news items) use virtualized rendering:

Fixed-Height Mode (VirtualList):

• Only renders items visible in viewport + 3-item overscan buffer
• Element pooling—reuses DOM nodes rather than creating new ones
• Invisible spacers maintain scroll position without rendering all items

Variable-Height Mode (WindowedList):

• Chunk-based rendering (10 items per chunk)
• Renders chunks on-scroll with 1-chunk buffer
• CSS containment for performance isolation

This reduces DOM node count from thousands to ~30, dramatically improving scroll performance.

Request Deduplication

Identical requests within a short window are deduplicated:

• Market quotes batch multiple symbols into single API call
• Concurrent layer toggles don't spawn duplicate fetches
• Promise.allSettled ensures one failing request doesn't block others

Efficient Data Updates

When refreshing data:

• Incremental updates: Only changed items trigger re-renders
• Stale-while-revalidate: Old data displays while fetch completes
• Delta compression: Baselines store 7-day/30-day deltas, not raw history

Prediction Market Filtering

The Prediction Markets panel focuses on geopolitically relevant markets, filtering out sports and entertainment.

Inclusion Keywords

Markets matching these topics are displayed:

• Conflicts: war, military, invasion, ceasefire, NATO, nuclear
• Countries: Russia, Ukraine, China, Taiwan, Iran, Israel, Gaza
• Leaders: Putin, Zelensky, Trump, Biden, Xi Jinping, Netanyahu
• Economics: Fed, interest rate, inflation, recession, tariffs, sanctions
• Global: UN, EU, treaties, summits, coups, refugees

Exclusion Keywords

Markets matching these are filtered out:

• Sports: NBA, NFL, FIFA, World Cup, championships, playoffs
• Entertainment: Oscars, movies, celebrities, TikTok, streaming

This ensures the panel shows markets like "Will Russia withdraw from Ukraine?" rather than "Will the Lakers win the championship?"

Panel Management

The dashboard organizes data into draggable, collapsible panels that persist user preferences across sessions.

Drag-to-Reorder

Panels can be reorganized by dragging:

1. Grab the panel header (grip icon appears on hover)
2. Drag to desired position
3. Drop to reorder
4. New order saves automatically to LocalStorage

This enables personalized layouts—put your most-watched panels at the top.

Panel Visibility

Toggle panels on/off via the Settings menu (⚙):

• Hidden panels: Don't render, don't fetch data
• Visible panels: Full functionality
• Collapsed panels: Header only, data still refreshes

Hiding a panel is different from disabling a layer—the panel itself doesn't appear in the interface.

Default Panel Order

Panels are organized by intelligence priority:

Persistence

Panel state survives browser restarts:

• LocalStorage: Panel order, visibility, collapsed state
• Automatic save: Changes persist immediately
• Per-device: Settings are browser-specific (not synced)

Mobile Experience

The dashboard is optimized for mobile devices with a streamlined interface that prioritizes usability on smaller screens.

First-Time Mobile Welcome

When accessing the dashboard on a mobile device for the first time, a welcome modal explains the mobile-optimized experience:

• Simplified view notice - Informs users they're seeing a curated mobile version
• Navigation tip - Explains regional view buttons and marker interaction
• "Don't show again" option - Checkbox to skip on future visits (persisted to localStorage)

Mobile-First Design

On screens narrower than 768px or touch devices:

• Compact map - Reduced height (40vh) to show more panels
• Single-column layout - Panels stack vertically for easy scrolling
• Hidden map labels - All marker labels are hidden to reduce visual clutter
• Fixed layer set - Layer toggle buttons are hidden; a curated set of layers is enabled by default
• Simplified controls - Map resize handle and pin button are hidden
• Touch-optimized markers - Expanded touch targets (44px) for easy tapping
• Hidden DEFCON indicator - Pentagon Pizza Index hidden to reduce header clutter
• Hidden FOCUS selector - Regional focus buttons hidden (use preset views instead)
• Compact header - Social link shows X logo instead of username text

Mobile Default Layers

The mobile experience focuses on the most essential intelligence layers:

Layers disabled by default on mobile (but available on desktop):

• Military bases, nuclear facilities, spaceports, minerals
• Undersea cables, pipelines, datacenters
• AIS vessels, military flights
• Protests, economic centers

This curated set provides situational awareness without overwhelming the interface or consuming excessive data/battery.

Touch Gestures

Map navigation supports:

• Pinch zoom - Two-finger zoom in/out
• Drag pan - Single-finger map movement
• Tap markers - Show popup (replaces hover)
• Double-tap - Quick zoom

Performance Considerations

Mobile optimizations reduce resource consumption:

Desktop Experience

On larger screens, the full feature set is available:

• Multi-column responsive panel grid
• All layer toggles accessible
• Map labels visible at appropriate zoom levels
• Resizable map section
• Pinnable map (keeps map visible while scrolling panels)
• Full DEFCON indicator with tension pairs
• FOCUS regional selector for rapid navigation

Energy Flow Detection

The correlation engine detects signals related to energy infrastructure and commodity markets.

Pipeline Keywords

The system monitors news for pipeline-related events:

Infrastructure terms: pipeline, pipeline explosion, pipeline leak, pipeline attack, pipeline sabotage, pipeline disruption, nord stream, keystone, druzhba

Flow indicators: gas flow, oil flow, supply disruption, transit halt, capacity reduction

Flow Drop Signals

When news mentions flow disruptions, two signal types may trigger:

Why This Matters

Energy supply disruptions create cascading effects:

1. Immediate: Spot price volatility
2. Short-term: Industrial production impacts
3. Long-term: Geopolitical leverage shifts

Early detection of flow drops—especially when markets haven't reacted—provides an information edge.

Signal Aggregator

The Signal Aggregator is the central nervous system that collects, groups, and summarizes intelligence signals from all data sources.

What It Aggregates

Country-Level Grouping

All signals are grouped by country code, creating a unified view:

{
  country: 'UA',  // Ukraine
  countryName: 'Ukraine',
  totalCount: 15,
  highSeverityCount: 3,
  signalTypes: Set(['military_flight', 'protest', 'internet_outage']),
  signals: [/* all signals for this country */]
}

Regional Convergence Detection

The aggregator identifies geographic convergence—when multiple signal types cluster in the same region:

Summary Output

The aggregator provides a real-time summary for dashboards and AI context:

[SIGNAL SUMMARY]
Top Countries: Ukraine (15 signals), Iran (12), Taiwan (8)
Convergence Zones: Baltic Sea (military_flight + military_vessel),
                   Tehran (protest + internet_outage)
Active Signal Types: 5 of 5
Total Signals: 47

Browser-Based Machine Learning

For offline resilience and reduced API costs, the system includes browser-based ML capabilities using ONNX Runtime Web.

Available Models

Fallback Strategy

Browser ML serves as the final fallback when cloud APIs are unavailable:

User requests summary
    ↓
1. Try Groq API (fast, free tier)
    ↓ (rate limited or error)
2. Try OpenRouter API (fallback provider)
    ↓ (unavailable)
3. Use Browser T5 (offline, always available)

Lazy Loading

Models are loaded on-demand to minimize initial page load:

• Models download only when first needed
• Progress indicator shows download status
• Once cached, models load instantly from IndexedDB

Worker Isolation

All ML inference runs in a dedicated Web Worker:

• Main thread remains responsive during inference
• 30-second timeout prevents hanging
• Automatic cleanup on errors

Limitations

Browser ML has constraints compared to cloud models:

Browser summarization is intentionally limited to 6 headlines × 80 characters to stay within model constraints.

Cross-Module Integration

Intelligence modules don't operate in isolation. Data flows between systems to enable composite analysis.

Data Flow Architecture

News Feeds → Clustering → Velocity Analysis → Hotspot Correlation
                ↓                                    ↓
         Topic Extraction                    CII Information Score
                ↓                                    ↓
         Keyword Monitors              Strategic Risk Overview
                                                     ↑
Military Flights → Near-Hotspot Detection ──────────┤
                                                     ↑
AIS Vessels → Chokepoint Monitoring ────────────────┤
                                                     ↑
ACLED/GDELT → Protest Events ───────────────────────┤
                       ↓
                CII Unrest Score

Module Dependencies

Alert Propagation

When a threshold is crossed:

1. Source module generates alert (e.g., CII spike)
2. Alert merges with related alerts (same country/region)
3. Strategic Risk receives composite alert
4. UI updates header badge and panel indicators

This ensures a single escalation (e.g., Ukraine military flights + protests + news spike) surfaces as one coherent signal rather than three separate alerts.

AI Insights Panel

The Insights Panel provides AI-powered analysis of the current news landscape, transforming raw headlines into actionable intelligence briefings.

World Brief Generation

Every 2 minutes (with rate limiting), the system generates a concise situation brief using a multi-provider fallback chain:

Caching Strategy: Redis server-side caching prevents redundant API calls. When the same headline set has been summarized recently, the cached result is returned immediately.

Focal Point Detection

The AI receives enriched context about focal points—entities that appear in both news coverage AND map signals. This enables intelligence-grade analysis:

[INTELLIGENCE SYNTHESIS]
FOCAL POINTS (entities across news + signals):
- IRAN [CRITICAL]: 12 news mentions + 5 map signals (military_flight, protest, internet_outage)
  KEY: "Iran protests continue..." | SIGNALS: military activity, outage detected
- TAIWAN [ELEVATED]: 8 news mentions + 3 map signals (military_vessel, military_flight)
  KEY: "Taiwan tensions rise..." | SIGNALS: naval vessels detected

Headline Scoring Algorithm

Not all news is equally important. Headlines are scored to identify the most significant stories for the briefing:

Score Boosters (high weight):

• Military keywords: war, invasion, airstrike, missile, deployment, mobilization
• Violence indicators: killed, casualties, clashes, massacre, crackdown
• Civil unrest: protest, uprising, coup, riot, martial law

Geopolitical Multipliers:

• Flashpoint regions: Iran, Russia, China, Taiwan, Ukraine, North Korea, Gaza
• Critical actors: NATO, Pentagon, Kremlin, Hezbollah, Hamas, Wagner

Score Reducers (demoted):

• Business context: CEO, earnings, stock, revenue, startup, data center
• Entertainment: celebrity, movie, streaming

This ensures military conflicts and humanitarian crises surface above routine business news.

Sentiment Analysis

Headlines are analyzed for overall sentiment distribution:

The overall sentiment balance provides a quick read on whether the news cycle is trending toward escalation or de-escalation.

Velocity Detection

Fast-moving stories are flagged when the same topic appears in multiple recent headlines:

• Headlines are grouped by shared keywords and entities
• Topics with 3+ mentions in 6 hours are marked as "high velocity"
• Displayed separately to highlight developing situations

Focal Point Detector

The Focal Point Detector is the intelligence synthesis layer that correlates news entities with map signals to identify "main characters" driving current events.

The Problem It Solves

Without synthesis, intelligence streams operate in silos:

• News feeds show 80+ sources with thousands of headlines
• Map layers display military flights, protests, outages independently
• No automated way to see that IRAN appears in news AND has military activity AND an internet outage

How It Works

1. Entity Extraction: Extract countries, companies, and organizations from all news clusters using the entity registry (600+ entities with aliases)

2. Signal Aggregation: Collect all map signals (military flights, protests, outages, vessels) and group by country

3. Cross-Reference: Match news entities with signal countries

4. Score & Rank: Calculate focal scores based on correlation strength

Focal Point Scoring

FocalScore = NewsScore + SignalScore + CorrelationBonus

NewsScore (0-40):
  base = min(20, mentionCount × 4)
  velocity = min(10, newsVelocity × 2)
  confidence = avgConfidence × 10

SignalScore (0-40):
  types = signalTypes.count × 10
  count = min(15, signalCount × 3)
  severity = highSeverityCount × 5

CorrelationBonus (0-20):
  +10 if entity appears in BOTH news AND signals
  +5 if news keywords match signal types (e.g., "military" + military_flight)
  +5 if related entities also have signals

Urgency Classification

Signal Type Icons

Focal points display icons indicating which signal types are active:

Example Output

A focal point for IRAN might show:

• Display: "Iran [CRITICAL] ✈️📢🌐"
• News: 12 mentions, velocity 0.5/hour
• Signals: 5 military flights, 3 protests, 1 outage
• Narrative: "12 news mentions | 5 military flights, 3 protests, 1 internet outage | 'Iran protests continue amid...'"
• Correlation Evidence: "Iran appears in both news (12) and map signals (9)"

Integration with CII

Focal point urgency levels feed into the Country Instability Index:

• Critical focal point → CII score boost for that country
• Ensures countries with multi-source convergence are properly flagged
• Prevents "silent" instability when news alone wouldn't trigger alerts

Natural Disaster Tracking

The Natural layer combines two authoritative sources for comprehensive disaster monitoring.

GDACS (Global Disaster Alert and Coordination System)

UN-backed disaster alert system providing official severity assessments:

Alert Levels:

NASA EONET (Earth Observatory Natural Event Tracker)

Near-real-time natural event detection from satellite observation:

Multi-Source Deduplication

When both GDACS and EONET report the same event:

1. Events within 100km and 48 hours are considered duplicates
2. GDACS severity takes precedence (human-verified)
3. EONET geometry provides more precise coordinates
4. Combined entry shows both source attributions

Filtering Logic

To prevent map clutter, natural events are filtered:

• Wildfires: Only events < 48 hours old (older fires are either contained or well-known)
• Earthquakes: M4.5+ globally, lower threshold for populated areas
• Storms: Only named storms or those with warnings

Military Surge Detection

The system detects unusual concentrations of military activity using two complementary algorithms.

Baseline-Based Surge Detection

Surges are detected by comparing current aircraft counts to historical baselines within defined military theaters:

Aircraft Categories Tracked:

Surge Severity

Military Theaters

Surge detection groups activity into strategic theaters:

Foreign Presence Detection

A separate system monitors for military operators outside their normal operating areas:

Example alert:

FOREIGN MILITARY PRESENCE: Persian Gulf
USAF: 3 aircraft detected (KC-135, RC-135W, E-3)
Severity: HIGH - Operator outside normal home regions

News Correlation

Both surge and foreign presence alerts query the Focal Point Detector for context:

1. Identify countries involved (aircraft operators, region countries)
2. Check focal points for those countries
3. If news correlation exists, attach headlines and evidence

Example with correlation:

MILITARY AIRLIFT SURGE: Middle East Theater
Current: 8 transport aircraft (2.5× baseline)
Aircraft: C-17 (3), KC-135 (3), C-130J (2)

NEWS CORRELATION:
Iran: "Iran protests continue amid military..."
→ Iran appears in both news (12) and map signals (9)

Strategic Posture Analysis

The AI Strategic Posture panel aggregates military aircraft and naval vessels across defined theaters, providing at-a-glance situational awareness of global force concentrations.

Strategic Theaters

Nine geographic theaters are monitored continuously, each with custom thresholds based on typical peacetime activity levels:

Strike Capability Assessment

Beyond raw counts, the system assesses whether forces in a theater constitute an offensive strike package—the combination of assets required for sustained combat operations.

Strike-Capable Criteria:

• Aerial refueling tankers (KC-135, KC-10, A330 MRTT)
• Airborne command and control (E-3 AWACS, E-7 Wedgetail)
• Combat aircraft (fighters, strike aircraft)

Each theater has custom thresholds reflecting realistic strike package sizes:

When all three criteria are met, the theater is flagged as STRIKE CAPABLE, indicating forces sufficient for sustained offensive operations.

Naval Vessel Integration

The panel augments aircraft data with real-time naval vessel positions from AIS tracking. Vessels are classified into categories:

Data Accumulation Note: AIS vessel data arrives via WebSocket stream and accumulates gradually. The panel automatically re-checks vessel counts at 30, 60, 90, and 120 seconds after initial load to capture late-arriving data.

Posture Levels

Elevated + Strike Capable is treated as a higher alert state than regular elevated status.

Trend Detection

Activity trends are computed from rolling historical data:

• Increasing (↗): Current activity >10% higher than previous period
• Stable (→): Activity within ±10% of previous period
• Decreasing (↘): Current activity >10% lower than previous period

Server-Side Caching

Theater posture computations run on edge servers with Redis caching:

This ensures consistent data across all users and minimizes redundant API calls to OpenSky Network.

Server-Side Risk Score API

Strategic risk and Country Instability Index (CII) scores are pre-computed server-side rather than calculated in the browser. This eliminates the "cold start" problem where new users would see no data while the system accumulated enough information to generate scores.

How It Works

The /api/risk-scores edge function:

1. Fetches recent protest/riot data from ACLED (7-day window)
2. Computes CII scores for 20 Tier 1 countries
3. Derives strategic risk from weighted top-5 CII scores
4. Caches results in Redis (10-minute TTL)

CII Score Calculation

Each country's score combines:

Baseline Risk (0–50 points): Static geopolitical risk based on historical instability, ongoing conflicts, and authoritarian governance.

Unrest Component (0–50 points): Recent protest and riot activity, weighted by event significance multiplier.

Information Component (0–25 points): News coverage intensity (proxy for international attention).

Security Component (0–25 points): Baseline plus riot contribution.

Event Significance Multipliers

Events in some countries carry more global significance than others:

Strategic Risk Derivation

The composite strategic risk score is computed as a weighted average of the top 5 CII scores:

Weights: [1.0, 0.85, 0.70, 0.55, 0.40] (total: 3.5)
Strategic Risk = (Σ CII[i] × weight[i]) / 3.5 × 0.7 + 15

The top countries contribute most heavily, with diminishing influence for lower-ranked countries.

Fallback Behavior

When ACLED data is unavailable (API errors, rate limits, expired auth):

1. Stale cache (1-hour TTL): Return recent scores with stale: true flag
2. Baseline fallback: Return scores using only static baseline values with baseline: true flag

This ensures the dashboard always displays meaningful data even during upstream outages.

Service Status Monitoring

The Service Status panel tracks the operational health of external services that World Monitor users may depend on.

Monitored Services

Status Levels

Why This Matters

External service outages can affect:

• AI summarization (Groq, OpenRouter outages)
• Deployment pipelines (Vercel, GitHub outages)
• API availability (Cloudflare, AWS outages)

Monitoring these services provides context when dashboard features behave unexpectedly.

Refresh Intervals

Different data sources update at different frequencies based on volatility and API constraints.

Polling Schedule

Real-Time Streams

AIS vessel tracking uses WebSocket for true real-time:

• Connection: Persistent WebSocket to Railway relay
• Messages: Position updates as vessels transmit
• Reconnection: Automatic with exponential backoff (5s → 10s → 20s)

User Control

Time range selector affects displayed data, not fetch frequency:

Historical filtering is client-side—all data is fetched but filtered for display.

Tech Stack

Map Rendering Architecture

The map uses a hybrid rendering strategy optimized for each platform:

Desktop (deck.gl + MapLibre GL):

• WebGL-accelerated layers handle thousands of markers smoothly
• MapLibre GL provides base map tiles (OpenStreetMap)
• GeoJSON, Scatterplot, Path, and Icon layers for different data types
• GPU-based clustering and picking for responsive interaction

Mobile (D3.js + TopoJSON):

• SVG rendering for battery efficiency
• Reduced marker count and simplified layers
• Touch-optimized interaction with larger hit targets
• Automatic fallback when WebGL unavailable

Key Libraries

• deck.gl: High-performance WebGL visualization layers
• MapLibre GL: Open-source map rendering engine
• D3.js: SVG map rendering, zoom behavior (mobile fallback)
• TopoJSON: Efficient geographic data encoding
• ONNX Runtime: Browser-based ML inference
• Custom HTML escaping: XSS prevention (DOMPurify pattern)

No External UI Frameworks

The entire UI is hand-crafted DOM manipulation—no React, Vue, or Angular. This keeps the bundle small (~250KB gzipped) and provides fine-grained control over rendering performance.

Build-Time Configuration

Vite injects configuration values at build time, enabling features like automatic version syncing:

This ensures the displayed version always matches the published package—no manual synchronization required.

// vite.config.ts
define: {
  __APP_VERSION__: JSON.stringify(pkg.version),
}

// App.ts
const header = `World Monitor v${__APP_VERSION__}`;

Installation

# Clone the repository
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

API Dependencies

The dashboard fetches data from various public APIs and data sources:

Optional API Keys

Some features require API credentials. Without them, the corresponding layer is hidden:

The dashboard functions fully without these keys—affected layers simply don't appear. Core functionality (news, markets, earthquakes, weather) requires no configuration.

Project Structure

src/
├── App.ts                    # Main application orchestrator
├── main.ts                   # Entry point
├── components/
│   ├── DeckGLMap.ts          # WebGL map with deck.gl + MapLibre (desktop)
│   ├── Map.ts                # D3.js SVG map (mobile fallback)
│   ├── MapContainer.ts       # Map wrapper with platform detection
│   ├── MapPopup.ts           # Contextual info popups
│   ├── SearchModal.ts        # Universal search (⌘K)
│   ├── SignalModal.ts        # Signal intelligence display with focal points
│   ├── PizzIntIndicator.ts   # Pentagon Pizza Index display
│   ├── VirtualList.ts        # Virtual/windowed scrolling
│   ├── InsightsPanel.ts      # AI briefings + focal point display
│   ├── EconomicPanel.ts      # FRED economic indicators
│   ├── GdeltIntelPanel.ts    # Topic-based intelligence (cyber, military, etc.)
│   ├── LiveNewsPanel.ts      # YouTube live news streams with channel switching
│   ├── NewsPanel.ts          # News feed with clustering
│   ├── MarketPanel.ts        # Stock/commodity display
│   ├── MonitorPanel.ts       # Custom keyword monitors
│   ├── CIIPanel.ts           # Country Instability Index display
│   ├── CascadePanel.ts       # Infrastructure cascade analysis
│   ├── StrategicRiskPanel.ts # Strategic risk overview dashboard
│   ├── StrategicPosturePanel.ts # AI strategic posture with theater analysis
│   ├── ServiceStatusPanel.ts # External service health monitoring
│   └── ...
├── config/
│   ├── feeds.ts              # 70+ RSS feeds, source tiers, regional sources
│   ├── geo.ts                # 30+ hotspots, conflicts, 55 cables, waterways, spaceports, minerals
│   ├── pipelines.ts          # 88 oil & gas pipelines
│   ├── ports.ts              # 61 strategic ports worldwide
│   ├── bases-expanded.ts     # 220+ military bases
│   ├── ai-datacenters.ts     # 313 AI clusters (filtered to 111)
│   ├── airports.ts           # 30 monitored US airports
│   ├── irradiators.ts        # IAEA gamma irradiator sites
│   ├── nuclear-facilities.ts # Global nuclear infrastructure
│   ├── markets.ts            # Stock symbols, sectors
│   ├── entities.ts           # 100+ entity definitions (companies, indices, commodities, countries)
│   └── panels.ts             # Panel configs, layer defaults, mobile optimizations
├── services/
│   ├── ais.ts                # WebSocket vessel tracking with density analysis
│   ├── military-vessels.ts   # Naval vessel identification and tracking
│   ├── military-flights.ts   # Aircraft tracking via OpenSky relay
│   ├── military-surge.ts     # Surge detection with news correlation
│   ├── cached-theater-posture.ts # Theater posture API client with caching
│   ├── wingbits.ts           # Aircraft enrichment (owner, operator, type)
│   ├── pizzint.ts            # Pentagon Pizza Index + GDELT tensions
│   ├── protests.ts           # ACLED + GDELT integration
│   ├── gdelt-intel.ts        # GDELT Doc API topic intelligence
│   ├── gdacs.ts              # UN GDACS disaster alerts
│   ├── eonet.ts              # NASA EONET natural events + GDACS merge
│   ├── flights.ts            # FAA delay parsing
│   ├── outages.ts            # Cloudflare Radar integration
│   ├── rss.ts                # RSS parsing with circuit breakers
│   ├── markets.ts            # Finnhub, Yahoo Finance, CoinGecko
│   ├── earthquakes.ts        # USGS integration
│   ├── weather.ts            # NWS alerts
│   ├── fred.ts               # Federal Reserve data
│   ├── oil-analytics.ts      # EIA oil prices, production, inventory
│   ├── usa-spending.ts       # USASpending.gov contracts & awards
│   ├── polymarket.ts         # Prediction markets (filtered)
│   ├── clustering.ts         # Jaccard similarity clustering
│   ├── correlation.ts        # Signal detection engine
│   ├── velocity.ts           # Velocity & sentiment analysis
│   ├── related-assets.ts     # Infrastructure near news events
│   ├── activity-tracker.ts   # New item detection & highlighting
│   ├── analysis-worker.ts    # Web Worker manager
│   ├── ml-worker.ts          # Browser ML inference (ONNX)
│   ├── summarization.ts      # AI briefings with fallback chain
│   ├── parallel-analysis.ts  # Concurrent headline analysis
│   ├── storage.ts            # IndexedDB snapshots & baselines
│   ├── data-freshness.ts     # Real-time data staleness tracking
│   ├── signal-aggregator.ts  # Central signal collection & grouping
│   ├── focal-point-detector.ts   # Intelligence synthesis layer
│   ├── entity-index.ts       # Entity lookup maps (by alias, keyword, sector)
│   ├── entity-extraction.ts  # News-to-entity matching for market correlation
│   ├── country-instability.ts    # CII scoring algorithm
│   ├── geo-convergence.ts        # Geographic convergence detection
│   ├── infrastructure-cascade.ts # Dependency graph and cascade analysis
│   └── cross-module-integration.ts # Unified alerts and strategic risk
├── workers/
│   └── analysis.worker.ts    # Off-thread clustering & correlation
├── utils/
│   ├── circuit-breaker.ts    # Fault tolerance pattern
│   ├── sanitize.ts           # XSS prevention (escapeHtml, sanitizeUrl)
│   ├── urlState.ts           # Shareable link encoding/decoding
│   └── analysis-constants.ts # Shared thresholds for worker sync
├── styles/
└── types/
api/                          # Vercel Edge serverless proxies
├── cloudflare-outages.js     # Proxies Cloudflare Radar
├── coingecko.js              # Crypto prices with validation
├── eia/[[...path]].js        # EIA petroleum data (oil prices, production)
├── faa-status.js             # FAA ground stops/delays
├── finnhub.js                # Stock quotes (batch, primary)
├── fred-data.js              # Federal Reserve economic data
├── gdelt-doc.js              # GDELT Doc API (topic intelligence)
├── gdelt-geo.js              # GDELT Geo API (event geolocation)
├── polymarket.js             # Prediction markets with validation
├── yahoo-finance.js          # Stock indices/commodities (backup)
├── opensky-relay.js          # Military aircraft tracking
├── wingbits.js               # Aircraft enrichment proxy
├── risk-scores.js            # Pre-computed CII and strategic risk (Redis cached)
├── theater-posture.js        # Theater-level force aggregation (Redis cached)
├── groq-summarize.js         # AI summarization with Groq API
└── openrouter-summarize.js   # AI summarization fallback via OpenRouter

Usage

Keyboard Shortcuts

• ⌘K / Ctrl+K - Open search
• ↑↓ - Navigate search results
• Enter - Select result
• Esc - Close modals

Map Controls

• Scroll - Zoom in/out
• Drag - Pan the map
• Click markers - Show detailed popup with full context
• Hover markers - Show tooltip with summary information
• Layer toggles - Show/hide data layers

Map Marker Design

Infrastructure markers (nuclear facilities, economic centers, ports) display without labels to reduce visual clutter. Full information is available through interaction:

This design prioritizes geographic awareness over label density—users can quickly scan for markers and then interact for context.

Panel Management

• Drag panels - Reorder layout
• Settings (⚙) - Toggle panel visibility

Shareable Links

The current view state is encoded in the URL, enabling:

• Bookmarking: Save specific views for quick access
• Sharing: Send colleagues a link to your exact map position and layer configuration
• Deep linking: Link directly to a specific region or feature

Encoded Parameters:

Example: ?lat=38.9&lon=-77&zoom=6&layers=bases,conflicts,hotspots

Values are validated and clamped to prevent invalid states.

Data Sources

News Feeds

Aggregates 70+ RSS feeds from major news outlets, government sources, and specialty publications with source-tier prioritization. Categories include world news, MENA, Africa, Latin America, Asia-Pacific, energy, technology, AI/ML, finance, government releases, defense/intel, think tanks, and international crisis organizations.

Geospatial Data

• Hotspots: 30+ global intelligence hotspots with keyword correlation (including Sahel, Haiti, Horn of Africa)
• Conflicts: 10+ active conflict zones with involved parties
• Military Bases: 220+ installations from US, NATO, Russia, China, and allies
• Pipelines: 88 operating oil/gas pipelines across all continents
• Undersea Cables: 55 major submarine cable routes
• Nuclear: 100+ power plants, weapons labs, enrichment facilities
• AI Infrastructure: 111 major compute clusters (≥10k GPUs)
• Strategic Waterways: 8 critical chokepoints
• Ports: 61 strategic ports (container, oil/LNG, naval, chokepoint)

Live APIs

• USGS: Earthquake feed (M4.5+ global)
• NASA EONET: Natural events (storms, wildfires, volcanoes, floods)
• NWS: Severe weather alerts (US)
• FAA: Airport delays and ground stops
• Cloudflare Radar: Internet outage detection
• AIS: Real-time vessel positions
• ACLED/GDELT: Protest and unrest events
• Yahoo Finance: Stock quotes and indices
• CoinGecko: Cryptocurrency prices
• FRED: Federal Reserve economic data
• Polymarket: Prediction market odds

Data Attribution

This project uses data from the following sources. Please respect their terms of use.

Aircraft Tracking

Data provided by The OpenSky Network. If you use this data in publications, please cite:

Matthias Schäfer, Martin Strohmeier, Vincent Lenders, Ivan Martinovic and Matthias Wilhelm. "Bringing Up OpenSky: A Large-scale ADS-B Sensor Network for Research". In Proceedings of the 13th IEEE/ACM International Symposium on Information Processing in Sensor Networks (IPSN), pages 83-94, April 2014.

Conflict & Protest Data

• ACLED: Armed Conflict Location & Event Data. Source: ACLED. Data must be attributed per their Attribution Policy.
• GDELT: Global Database of Events, Language, and Tone. Source: The GDELT Project.

Financial Data

• Stock Quotes: Powered by Finnhub (primary), with Yahoo Finance as backup for indices and commodities
• Cryptocurrency: Powered by CoinGecko API
• Economic Indicators: Data from FRED, Federal Reserve Bank of St. Louis

Geophysical Data

• Earthquakes: U.S. Geological Survey, ANSS Comprehensive Catalog
• Natural Events: NASA EONET - Earth Observatory Natural Event Tracker (storms, wildfires, volcanoes, floods)
• Weather Alerts: National Weather Service - Open data, free to use

Infrastructure & Transport

• Airport Delays: FAA Air Traffic Control System Command Center
• Vessel Tracking: AISstream real-time AIS data
• Internet Outages: Cloudflare Radar (CC BY-NC 4.0)

Other Sources

• Prediction Markets: Polymarket

Acknowledgments

Original dashboard concept inspired by Reggie James (@HipCityReg) - with thanks for the vision of a comprehensive situation awareness tool

Special thanks to Yanal at Wingbits for providing API access for aircraft enrichment data, enabling military aircraft classification and ownership tracking

Thanks to @fai9al for the inspiration and original PR that led to the Tech Monitor variant

Limitations & Caveats

This project is a proof of concept demonstrating what's possible with publicly available data. While functional, there are important limitations:

Data Completeness

Some data sources require paid accounts for full access:

• ACLED: Free tier has API restrictions; Research tier required for programmatic access
• OpenSky Network: Rate-limited; commercial tiers offer higher quotas
• Satellite AIS: Global coverage requires commercial providers (Spire, Kpler, etc.)

The dashboard works with free tiers but may have gaps in coverage or update frequency.

AIS Coverage Bias

The Ships layer uses terrestrial AIS receivers via AISStream.io. This creates a geographic bias:

• Strong coverage: European waters, Atlantic, major ports
• Weak coverage: Middle East, open ocean, remote regions

Terrestrial receivers only detect vessels within ~50km of shore. Satellite AIS (commercial) provides true global coverage but is not included in this free implementation.

Blocked Data Sources

Some publishers block requests from cloud providers (Vercel, Railway, AWS):

• RSS feeds from certain outlets may fail with 403 errors
• This is a common anti-bot measure, not a bug in the dashboard
• Affected feeds are automatically disabled via circuit breakers

The system degrades gracefully—blocked sources are skipped while others continue functioning.

Roadmap

See ROADMAP.md for detailed planning. Recent intelligence enhancements:

Completed

• ✅ Focal Point Detection - Intelligence synthesis correlating news entities with map signals
• ✅ AI-Powered Briefings - Groq/OpenRouter/Browser ML fallback chain for summarization
• ✅ Military Surge Detection - Alerts when multiple operators converge on regions
• ✅ News-Signal Correlation - Surge alerts include related focal point context
• ✅ GDACS Integration - UN disaster alert system for earthquakes, floods, cyclones, volcanoes
• ✅ WebGL Map (deck.gl) - High-performance rendering for desktop users
• ✅ Browser ML Fallback - ONNX Runtime for offline summarization capability
• ✅ Multi-Signal Geographic Convergence - Alerts when 3+ data types converge on same region within 24h
• ✅ Country Instability Index (CII) - Real-time composite risk score for 20 Tier-1 countries
• ✅ Infrastructure Cascade Visualization - Dependency graph showing downstream effects of disruptions
• ✅ Strategic Risk Overview - Unified alert system with cross-module correlation and deduplication
• ✅ GDELT Topic Intelligence - Categorized feeds for military, cyber, nuclear, and sanctions topics
• ✅ OpenSky Authentication - OAuth2 credentials for military aircraft tracking via relay
• ✅ Human-Readable Locations - Convergence alerts show place names instead of coordinates
• ✅ Data Freshness Tracking - Status panel shows enabled/disabled state for all feeds
• ✅ CII Scoring Bias Prevention - Log scaling and conflict zone floors prevent news volume bias
• ✅ Alert Warmup Period - Suppresses false positives on dashboard startup
• ✅ Significant Protest Filtering - Map shows only riots and high-severity protests
• ✅ Intelligence Findings Detail Modal - Click any alert for full context and component breakdown
• ✅ Build-Time Version Sync - Header version auto-syncs with package.json
• ✅ Tech Monitor Variant - Dedicated technology sector dashboard with startup ecosystems, cloud regions, and tech events
• ✅ Smart Marker Clustering - Geographic grouping of nearby markers with click-to-expand popups
• ✅ Variant Switcher UI - Compact orbital navigation between World Monitor and Tech Monitor
• ✅ CII Learning Mode - 15-minute calibration period with visual progress indicator
• ✅ Regional Tech Coverage - Verified tech HQ data for MENA, Europe, Asia-Pacific hubs
• ✅ Service Status Panel - External service health monitoring (AI providers, cloud platforms)
• ✅ AI Strategic Posture Panel - Theater-level force aggregation with strike capability assessment
• ✅ Server-Side Risk Score API - Pre-computed CII and strategic risk scores with Redis caching
• ✅ Naval Vessel Classification - Known vessel database with hull number matching and AIS type inference
• ✅ Strike Capability Detection - Assessment of offensive force packages (tankers + AWACS + fighters)
• ✅ Theater Posture Thresholds - Custom elevated/critical thresholds for each strategic theater

Planned

High Priority:

• Temporal Anomaly Detection - Flag activity unusual for time of day/week/year (e.g., "military flights 3x normal for Tuesday")
• Trade Route Risk Scoring - Real-time supply chain vulnerability for major shipping routes (Asia→Europe, Middle East→Europe, etc.)

Medium Priority:

• Historical Playback - Review past dashboard states with timeline scrubbing
• Election Calendar Integration - Auto-boost sensitivity 30 days before major elections
• Choropleth CII Map Layer - Country-colored overlay showing instability scores

Future Enhancements:

• Alert Webhooks - Push critical alerts to Slack, Discord, email
• Custom Country Watchlists - User-defined Tier-2 country monitoring
• Additional Data Sources - World Bank, IMF, OFAC sanctions, UNHCR refugee data, FAO food security
• Think Tank Feeds - RUSI, Chatham House, ECFR, CFR, Wilson Center, CNAS, Arms Control Association

The full ROADMAP.md documents implementation details, API endpoints, and 30+ free data sources for future integration.

Design Philosophy

Information density over aesthetics. Every pixel should convey signal. The dark interface minimizes eye strain during extended monitoring sessions. Panels are collapsible, draggable, and hideable—customize to show only what matters.

Authority matters. Not all sources are equal. Wire services and official government channels are prioritized over aggregators and blogs. When multiple sources report the same story, the most authoritative source is displayed as primary.

Correlation over accumulation. Raw news feeds are noise. The value is in clustering related stories, detecting velocity changes, and identifying cross-source patterns. A single "Broadcom +2.5% explained by AI chip news" signal is more valuable than showing both data points separately.

Signal, not noise. Deduplication is aggressive. The same market move doesn't generate repeated alerts. Signals include confidence scores so you can prioritize attention. Alert fatigue is the enemy of situational awareness.

Knowledge-first matching. Simple keyword matching produces false positives. The entity knowledge base understands that AVGO is Broadcom, that Broadcom competes with Nvidia, and that both are in semiconductors. This semantic layer transforms naive string matching into intelligent correlation.

Fail gracefully. External APIs are unreliable. Circuit breakers prevent cascading failures. Cached data displays during outages. The status panel shows exactly what's working and what isn't—no silent failures.

Local-first. No accounts, no cloud sync. All preferences and history stored locally. The only network traffic is fetching public data. Your monitoring configuration is yours alone.

Compute where it matters. CPU-intensive operations (clustering, correlation) run in Web Workers to keep the UI responsive. The main thread handles only rendering and user interaction.

System Architecture

Data Flow Overview

                                    ┌─────────────────────────────────┐
                                    │     External Data Sources       │
                                    │  RSS Feeds, APIs, WebSockets    │
                                    └─────────────┬───────────────────┘
                                                  │
                         ┌────────────────────────┼────────────────────────┐
                         │                        │                        │
                         ▼                        ▼                        ▼
               ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
               │   RSS Parser    │    │    API Client   │    │  WebSocket Hub  │
               │  (News Feeds)   │    │ (USGS, FAA...)  │    │ (AIS, Markets)  │
               └────────┬────────┘    └────────┬────────┘    └────────┬────────┘
                        │                      │                      │
                        └──────────────────────┼──────────────────────┘
                                               │
                                               ▼
                             ┌─────────────────────────────────┐
                             │      Circuit Breakers           │
                             │  (Rate Limiting, Retry Logic)   │
                             └─────────────┬───────────────────┘
                                           │
                         ┌─────────────────┼─────────────────┐
                         │                 │                 │
                         ▼                 ▼                 ▼
               ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
               │  Data Freshness │ │  Search Index   │ │   Web Worker    │
               │    Tracker      │ │  (Searchables)  │ │  (Clustering)   │
               └────────┬────────┘ └────────┬────────┘ └────────┬────────┘
                        │                   │                   │
                        └───────────────────┼───────────────────┘
                                            │
                                            ▼
                             ┌─────────────────────────────────┐
                             │         App State               │
                             │  (Map, Panels, Intelligence)    │
                             └─────────────┬───────────────────┘
                                           │
                                           ▼
                             ┌─────────────────────────────────┐
                             │      Rendering Pipeline         │
                             │  D3.js Map + React-like Panels  │
                             └─────────────────────────────────┘

Update Cycles

Different data types refresh at different intervals based on volatility and API limits:

Error Handling Strategy

The system implements defense-in-depth for external service failures:

Circuit Breakers

• Each external service has an independent circuit breaker
• After 3 consecutive failures, the circuit opens for 60 seconds
• Partial failures don't cascade to other services
• Status panel shows exact failure states

Graceful Degradation

• Stale cached data displays during outages (with timestamp warning)
• Failed services are automatically retried on next cycle
• Critical data (news, markets) has backup sources

User Feedback

• Real-time status indicators in the header
• Specific error messages in the status panel
• No silent failures—every data source state is visible

Build-Time Optimization

The project uses Vite for optimal production builds:

Code Splitting

• Web Worker code is bundled separately
• Config files (tech-geo.ts, pipelines.ts) are tree-shaken
• Lazy-loaded panels reduce initial bundle size

Variant Builds

• npm run build - Standard geopolitical dashboard
• npm run build:tech - Tech sector variant with different defaults
• Both share the same codebase, configured via environment variables

Asset Optimization

• TopoJSON geography data is pre-compressed
• Static config data is inlined at build time
• CSS is minified and autoprefixed

Security Considerations

Client-Side Security

• All user input is sanitized via escapeHtml() before rendering
• URLs are validated via sanitizeUrl() before href assignment
• No innerHTML with user-controllable content

API Security

• Sensitive API keys are stored server-side only
• Proxy functions validate and sanitize parameters
• Geographic coordinates are clamped to valid ranges

Privacy

• No user accounts or cloud storage
• All preferences stored in localStorage
• No telemetry beyond basic Vercel analytics (page views only)

Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, improving documentation, or suggesting ideas, your help makes this project better.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:
   bashCopy

   git clone https://github.com/YOUR_USERNAME/worldmonitor.git
   cd worldmonitor
   

3. Install dependencies:
   bashCopy

   npm install
   

4. Create a feature branch:
   bashCopy

   git checkout -b feature/your-feature-name
   

5. Start the development server:
   bashCopy

   npm run dev
   

Code Style & Conventions

This project follows specific patterns to maintain consistency:

TypeScript

• Strict type checking enabled—avoid any where possible
• Use interfaces for data structures, types for unions
• Prefer const over let, never use var

Architecture

• Services (src/services/) handle data fetching and business logic
• Components (src/components/) handle UI rendering
• Config (src/config/) contains static data and constants
• Utils (src/utils/) contain shared helper functions

Security

• Always use escapeHtml() when rendering user-controlled or external data
• Use sanitizeUrl() for any URLs from external sources
• Validate and clamp parameters in API proxy endpoints

Performance

• Expensive computations should run in the Web Worker
• Use virtual scrolling for lists with 50+ items
• Implement circuit breakers for external API calls

No Comments Policy

• Code should be self-documenting through clear naming
• Only add comments for non-obvious algorithms or workarounds
• Never commit commented-out code

Submitting a Pull Request

1. Ensure your code builds:

   bashCopy

   npm run build
   

2. Test your changes manually in the browser

3. Write a clear commit message:

   Copy

   Add earthquake magnitude filtering to map layer
   
   - Adds slider control to filter by minimum magnitude
   - Persists preference to localStorage
   - Updates URL state for shareable links
   

4. Push to your fork:

   bashCopy

   git push origin feature/your-feature-name
   

5. Open a Pull Request with:

   • A clear title describing the change
   • Description of what the PR does and why
   • Screenshots for UI changes
   • Any breaking changes or migration notes

What Makes a Good PR

Types of Contributions

🐛 Bug Fixes

• Found something broken? Fix it and submit a PR
• Include steps to reproduce in the PR description

✨ New Features

• New data layers (with public API sources)
• UI/UX improvements
• Performance optimizations
• New signal detection algorithms

📊 Data Sources

• Additional RSS feeds for news aggregation
• New geospatial datasets (bases, infrastructure, etc.)
• Alternative APIs for existing data

📝 Documentation

• Clarify existing documentation
• Add examples and use cases
• Fix typos and improve readability

🔒 Security

• Report vulnerabilities via GitHub Issues (non-critical) or email (critical)
• XSS prevention improvements
• Input validation enhancements

Review Process

1. Automated checks run on PR submission
2. Maintainer review within a few days
3. Feedback addressed through commits to the same branch
4. Merge once approved

PRs that don't follow the code style or introduce security issues will be asked to revise.

Development Tips

Adding a New Data Layer

1. Create service in src/services/ for data fetching
2. Add layer toggle in src/components/Map.ts
3. Add rendering logic for map markers/overlays
4. Add to help panel documentation
5. Update README with layer description

Adding a New API Proxy

1. Create handler in api/ directory
2. Implement input validation (see existing proxies)
3. Add appropriate cache headers
4. Document any required environment variables

Debugging

• Browser DevTools → Network tab for API issues
• Console logs prefixed with [ServiceName] for easy filtering
• Circuit breaker status visible in browser console

License

MIT

Author

Elie Habib

Built for situational awareness and open-source intelligence gathering.