Documentation Index
Fetch the complete documentation index at: https://worldmonitor.app/docs/llms.txt
Use this file to discover all available pages before exploring further.
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
| Layer | Technology | Purpose |
|---|
| Language | TypeScript 5.x | Type safety across 60+ source files |
| Build | Vite | Fast HMR, optimized production builds |
| Map (Desktop) | deck.gl + MapLibre GL | WebGL-accelerated rendering for large datasets |
| Map (Mobile) | D3.js + TopoJSON | SVG fallback for battery efficiency |
| Concurrency | Web Workers | Off-main-thread clustering and correlation |
| AI/ML | ONNX Runtime Web | Browser-based inference for offline summarization |
| Networking | WebSocket + REST | Real-time AIS stream, HTTP for other APIs |
| Storage | IndexedDB | Snapshots, baselines (megabytes of state) |
| Preferences | LocalStorage | User settings, monitors, panel order |
| Deployment | Vercel Edge | Serverless 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:
| Variable | Source | Purpose |
|---|
__APP_VERSION__ | package.json version field | Header displays current version |
// 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
.proto files, regenerate before building or pushing:
make generate # regenerate TypeScript clients, servers, and OpenAPI docs
API Dependencies
The dashboard fetches data from various public APIs and data sources:
| Service | Data | Auth Required |
|---|
| RSS2JSON | News feed parsing | No |
| Finnhub | Stock quotes (primary) | Yes (free) |
| Yahoo Finance | Stock indices & commodities (backup) | No |
| CoinGecko | Cryptocurrency prices | No |
| USGS | Earthquake data | No |
| NASA EONET | Natural events (storms, fires, volcanoes, floods) | No |
| NWS | Weather alerts | No |
| FRED | Economic indicators (Fed data) | No |
| EIA | Oil analytics (prices, production, inventory) | Yes (free) |
| USASpending.gov | Federal government contracts & awards | No |
| Polymarket | Prediction markets | No |
| ACLED | Armed conflict & protest data | Yes (free) |
| GDELT Geo | News-derived event geolocation + tensions | No |
| GDELT Doc | Topic-based intelligence feeds (cyber, military, nuclear) | No |
| FAA NASSTATUS | Airport delay status | No |
| Cloudflare Radar | Internet outage data | Yes (free) |
| AISStream | Live vessel positions | Yes (relay) |
| OpenSky Network | Military aircraft tracking | Yes (free) |
| Wingbits | Aircraft enrichment (owner, operator) | Yes (free) |
| PizzINT | Pentagon-area activity metrics | No |
Optional API Keys
Some features require API credentials. Without them, the corresponding layer is hidden:
| Variable | Service | How to Get |
|---|
FINNHUB_API_KEY | Stock quotes (primary) | Free registration at finnhub.io |
EIA_API_KEY | Oil analytics | Free registration at eia.gov/opendata |
VITE_WS_RELAY_URL | AIS vessel tracking | Deploy AIS relay or use hosted service |
VITE_OPENSKY_RELAY_URL | Military aircraft | Deploy relay with OpenSky credentials |
OPENSKY_CLIENT_ID | OpenSky auth (relay) | Free registration at opensky-network.org |
OPENSKY_CLIENT_SECRET | OpenSky auth (relay) | API key from OpenSky account settings |
CLOUDFLARE_API_TOKEN | Internet outages | Free Cloudflare account with Radar access |
ACLED_ACCESS_TOKEN | Protest data (server-side) | Free registration at acleddata.com |
WINGBITS_API_KEY | Aircraft enrichment | Contact Wingbits for API access |
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 # 500+ 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.