Skip to main content
This guide covers everything you need to set up WorldMonitor locally, from prerequisites and installation to understanding the project structure and API dependencies.

Tech Stack

LayerTechnologyPurpose
LanguageTypeScript 5.xType safety across 60+ source files
BuildViteFast HMR, optimized production builds
Map (Desktop)deck.gl + MapLibre GLWebGL-accelerated rendering for large datasets
Map (Mobile)D3.js + TopoJSONSVG fallback for battery efficiency
ConcurrencyWeb WorkersOff-main-thread clustering and correlation
AI/MLONNX Runtime WebBrowser-based inference for offline summarization
NetworkingWebSocket + RESTReal-time AIS stream, HTTP for other APIs
StorageIndexedDBSnapshots, baselines (megabytes of state)
PreferencesLocalStorageUser settings, monitors, panel order
DeploymentVercel EdgeServerless proxies with global distribution

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:
VariableSourcePurpose
__APP_VERSION__package.json version fieldHeader displays current version
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

Requirements: Go 1.21+ and Node.js 18+.
# Clone the repository
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor

# Install everything (buf, sebuf plugins, npm deps, proto deps)
make install

# Start development server
npm run dev

# Build for production
npm run build
If you modify any .proto files, regenerate before building or pushing:
make generate   # regenerate TypeScript clients, servers, and OpenAPI docs
See Adding Endpoints for the full proto workflow.

API Dependencies

The dashboard fetches data from various public APIs and data sources:
ServiceDataAuth Required
RSS2JSONNews feed parsingNo
FinnhubStock quotes (primary)Yes (free)
Yahoo FinanceStock indices & commodities (backup)No
CoinGeckoCryptocurrency pricesNo
USGSEarthquake dataNo
NASA EONETNatural events (storms, fires, volcanoes, floods)No
NWSWeather alertsNo
FREDEconomic indicators (Fed data)No
EIAOil analytics (prices, production, inventory)Yes (free)
USASpending.govFederal government contracts & awardsNo
PolymarketPrediction marketsNo
ACLEDArmed conflict & protest dataYes (free)
GDELT GeoNews-derived event geolocation + tensionsNo
GDELT DocTopic-based intelligence feeds (cyber, military, nuclear)No
FAA NASSTATUSAirport delay statusNo
Cloudflare RadarInternet outage dataYes (free)
AISStreamLive vessel positionsYes (relay)
OpenSky NetworkMilitary aircraft trackingYes (free)
WingbitsAircraft enrichment (owner, operator)Yes (free)
PizzINTPentagon-area activity metricsNo

Optional API Keys

Some features require API credentials. Without them, the corresponding layer is hidden:
VariableServiceHow to Get
FINNHUB_API_KEYStock quotes (primary)Free registration at finnhub.io
EIA_API_KEYOil analyticsFree registration at eia.gov/opendata
VITE_WS_RELAY_URLAIS vessel trackingDeploy AIS relay or use hosted service
VITE_OPENSKY_RELAY_URLMilitary aircraftDeploy relay with OpenSky credentials
OPENSKY_CLIENT_IDOpenSky auth (relay)Free registration at opensky-network.org
OPENSKY_CLIENT_SECRETOpenSky auth (relay)API key from OpenSky account settings
CLOUDFLARE_API_TOKENInternet outagesFree Cloudflare account with Radar access
ACLED_ACCESS_TOKENProtest data (server-side)Free registration at acleddata.com
WINGBITS_API_KEYAircraft enrichmentContact Wingbits for API access
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 (Cmd+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, 86 cables, waterways, spaceports, minerals
│   ├── pipelines.ts          # 88 oil & gas pipelines
│   ├── ports.ts              # 62 strategic ports worldwide
│   ├── bases-expanded.ts     # 226 military bases
│   ├── ai-datacenters.ts     # 313 AI compute clusters (Epoch AI dataset)
│   ├── airports.ts           # 111 airports across 5 regions
│   ├── irradiators.ts        # IAEA gamma irradiator sites
│   ├── nuclear-facilities.ts # Global nuclear infrastructure
│   ├── markets.ts            # Stock symbols, sectors
│   ├── entities.ts           # 66 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

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 Schafer, 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

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

Infrastructure & Transport

Other Sources

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.

License

World Monitor is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) for non-commercial use. Commercial use requires a separate license. See the License page for full details on what this means in practice.

Author

Elie Habib
Built for situational awareness and open-source intelligence gathering.