worldmonitor Documentation

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

81,304 stars TypeScript TypeScript 1 file ยท ~6,789 tokens #agent#ai#dashboard#geopolitics#mcp#mcp-server#monitoring#news
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy worldmonitor on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name worldmonitor -p 3000:3000 --restart always worldmonitor:latest
Configured Services & Ports
โš™๏ธ worldmonitor
image: worldmonitor:latest
๐Ÿ”Œ Ports: ${WM_PORT:-3000}:8080
โš™๏ธ ais-relay
image: worldmonitor-ais-relay:latest
โš™๏ธ redis
image: docker.io/redis:7-alpine
โš™๏ธ redis-rest
image: worldmonitor-redis-rest:latest
๐Ÿ”Œ Ports: 127.0.0.1:8079:80
docker-compose.yml
yaml (docker-compose.yml) 
# =============================================================================
# World Monitor โ€” Docker / Podman Compose
# =============================================================================
# Self-contained stack: app + Redis + AIS relay.
#
# Quick start:
#   cp .env.example .env        # add your API keys
#   docker compose up -d --build
#
# The app will be available at http://localhost:3000
# =============================================================================

services:

  worldmonitor:
    build:
      context: .
      dockerfile: Dockerfile
    image: worldmonitor:latest
    container_name: worldmonitor
    ports:
      - "${WM_PORT:-3000}:8080"
    environment:
      UPSTASH_REDIS_REST_URL: "http://redis-rest:80"
      UPSTASH_REDIS_REST_TOKEN: "${REDIS_TOKEN:?REDIS_TOKEN required โ€” generate with: openssl rand -hex 32}"
      WM_SESSION_SECRET: "${WM_SESSION_SECRET:?WM_SESSION_SECRET required โ€” generate with: openssl rand -hex 32}"
      LOCAL_API_PORT: "46123"
      LOCAL_API_MODE: "docker"
      LOCAL_API_CLOUD_FALLBACK: "false"
      WM_TRUSTED_PROXY_CIDRS: "${WM_TRUSTED_PROXY_CIDRS:-}"
      WS_RELAY_URL: "http://ais-relay:3004"
      # Operator keys accepted by MCP and REST through X-WorldMonitor-Key.
      WORLDMONITOR_VALID_KEYS: "${WORLDMONITOR_VALID_KEYS:-}"
      RELAY_SHARED_SECRET: "${RELAY_SHARED_SECRET:?RELAY_SHARED_SECRET required โ€” generate with: openssl rand -hex 32}"
      WORLDMONITOR_RELAY_KEY: "${WORLDMONITOR_RELAY_KEY:-}"
      # LLM provider (any OpenAI-compatible endpoint)
      LLM_API_URL: "${LLM_API_URL:-}"
      LLM_API_KEY: "${LLM_API_KEY:-}"
      LLM_MODEL: "${LLM_MODEL:-}"
      OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}"
      # Data source API keys (optional โ€” features degrade gracefully)
      AISSTREAM_API_KEY: "${AISSTREAM_API_KEY:-}"
      FINNHUB_API_KEY: "${FINNHUB_API_KEY:-}"
      EIA_API_KEY: "${EIA_API_KEY:-}"
      FRED_API_KEY: "${FRED_API_KEY:-}"
      ACLED_EMAIL: "${ACLED_EMAIL:-}"
      ACLED_PASSWORD: "${ACLED_PASSWORD:-}"
      ACLED_ACCESS_TOKEN: "${ACLED_ACCESS_TOKEN:-}"
      NASA_FIRMS_API_KEY: "${NASA_FIRMS_API_KEY:-}"
      CLOUDFLARE_API_TOKEN: "${CLOUDFLARE_API_TOKEN:-}"
      AVIATIONSTACK_API: "${AVIATIONSTACK_API:-}"
      TRAVELPAYOUTS_API_TOKEN: "${TRAVELPAYOUTS_API_TOKEN:-}"
    # Docker secrets (recommended for API keys โ€” keeps them out of docker inspect).
    # Create secrets/ dir with one file per key, then uncomment below.
    # See SELF_HOSTING.md or docker-compose.override.yml for details.
    # secrets:
    #   - OPENROUTER_API_KEY
    #   - AISSTREAM_API_KEY
    #   - FINNHUB_API_KEY
    #   - FRED_API_KEY
    #   - NASA_FIRMS_API_KEY
    #   - LLM_API_KEY
    depends_on:
      redis-rest:
        condition: service_started
      ais-relay:
        condition: service_started
    restart: unless-stopped

  ais-relay:
    build:
      context: .
      dockerfile: Dockerfile.relay
    image: worldmonitor-ais-relay:latest
    container_name: worldmonitor-ais-relay
    environment:
      RELAY_SHARED_SECRET: "${RELAY_SHARED_SECRET:?RELAY_SHARED_SECRET required โ€” generate with: openssl rand -hex 32}"
      AISSTREAM_API_KEY: "${AISSTREAM_API_KEY:-}"
      FINNHUB_API_KEY: "${FINNHUB_API_KEY:-}"
      MARKET_YAHOO_REFRESH_INTERVAL_MS: "${MARKET_YAHOO_REFRESH_INTERVAL_MS:-900000}"
      UPSTASH_REDIS_REST_URL: "http://redis-rest:80"
      UPSTASH_REDIS_REST_TOKEN: "${REDIS_TOKEN:?REDIS_TOKEN required โ€” generate with: openssl rand -hex 32}"
      UPSTASH_ALLOW_INSECURE_HTTP: "true"
      UCDP_ACCESS_TOKEN: "${UCDP_ACCESS_TOKEN:-}"
      # Optional: Jev shadows the classify seed and records disagreements; it decides nothing.
      TYPESAFE_API_KEY: "${TYPESAFE_API_KEY:-}"
      TYPESAFE_BASE_URL: "${TYPESAFE_BASE_URL:-}"
      # Classify reads list-feed-digest from this install, not production (#7437).
      # Do not depends_on worldmonitor here โ€” the app already depends_on ais-relay.
      # Transient connection retries cover the compose boot race instead.
      API_BASE_URL: "${API_BASE_URL:-http://worldmonitor:8080}"
      WORLDMONITOR_RELAY_KEY: "${WORLDMONITOR_RELAY_KEY:-}"
      PORT: "3004"
    depends_on:
      redis-rest:
        condition: service_started
    restart: unless-stopped

  redis:
    image: docker.io/redis:7-alpine
    container_name: worldmonitor-redis
    # --requirepass closes off the network so any future sidecar / compromised
    # dependency added to the worldmonitor network can't read or write cache
    # entries without the password. Defense-in-depth alongside the REST token.
    command: >
      redis-server
      --requirepass "${REDIS_PASSWORD:?REDIS_PASSWORD required โ€” generate with: openssl rand -hex 32}"
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    restart: unless-stopped

  redis-rest:
    build:
      context: docker
      dockerfile: Dockerfile.redis-rest
    image: worldmonitor-redis-rest:latest
    container_name: worldmonitor-redis-rest
    # The proxy buffers each accepted request body in full (SRH_MAX_BODY_BYTES,
    # 16MB default), so concurrent large publishes multiply. Measured: 64
    # concurrent 16MB POSTs reached ~933MB RSS. Buffers are off-heap, so a Node
    # heap flag would not contain them โ€” bound it at the container, the same way
    # the redis service is bounded by --maxmemory. 512m leaves ~7x headroom over
    # one max-size publish (16MB body + concat + UTF-16 string โ‰ˆ 64MB transient).
    mem_limit: 512m
    ports:
      - "127.0.0.1:8079:80"
    environment:
      SRH_TOKEN: "${REDIS_TOKEN:?REDIS_TOKEN required โ€” generate with: openssl rand -hex 32}"
      # Defense-in-depth: the redis service's --requirepass already fails
      # compose validation if REDIS_PASSWORD is unset, but the explicit
      # :? here protects against a future PR removing --requirepass or
      # copying this connection string into a new service.
      SRH_CONNECTION_STRING: "redis://:${REDIS_PASSWORD:?REDIS_PASSWORD required โ€” generate with: openssl rand -hex 32}@redis:6379"
    depends_on:
      - redis
    restart: unless-stopped

# Docker secrets โ€” uncomment and point to your secret files.
# Example: echo "sk-or-abc123" > secrets/openrouter_api_key.txt
# secrets:
#   OPENROUTER_API_KEY:
#     file: ./secrets/openrouter_api_key.txt
#   AISSTREAM_API_KEY:
#     file: ./secrets/aisstream_api_key.txt
#   FINNHUB_API_KEY:
#     file: ./secrets/finnhub_api_key.txt
#   FRED_API_KEY:
#     file: ./secrets/fred_api_key.txt
#   NASA_FIRMS_API_KEY:
#     file: ./secrets/nasa_firms_api_key.txt
#   LLM_API_KEY:
#     file: ./secrets/llm_api_key.txt

volumes:
  redis-data:

1. Project Overview & Quickstart (koala73/worldmonitor)

File: README.md

World Monitor

็ฎ€ไฝ“ไธญๆ–‡ | ๆ—ฅๆœฌ่ชž

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









What It Does

  • Curated news feeds across global and regional categories, AI-synthesized into briefs
  • Dual map engine โ€” 3D globe (globe.gl) and WebGL flat map (deck.gl) with a shared map-layer catalog
  • Panel inventory โ€” concrete panel implementations across specialized variants
  • Cross-stream correlation โ€” military, economic, disaster, and escalation signal convergence
  • Country Instability Index (CII) โ€” server-authoritative CII v8 stress scoring for the Tier-1 registry
  • Finance radar โ€” stock exchanges, commodities, crypto, and a market composite
  • Local AI โ€” run everything with Ollama, no API keys required
  • Site variants from a single codebase (world, tech, finance, commodity, happy, energy)
  • Native desktop app (Tauri 2) for macOS, Windows, and Linux
  • Multilingual UI with native-language feeds and RTL support

For the full feature list, architecture, data sources, and algorithms, see the documentation.

Support Status

All site variants and desktop binaries are built from a single codebase and ship from the same release process. The table below clarifies maintenance status so you know which surfaces are safe to depend on.

Surface Status Notes
worldmonitor.app, tech., finance., commodity., happy., energy. Stable Public deployments built from this repo, actively maintained
Desktop binaries (Windows / macOS Apple Silicon / macOS Intel / Linux AppImage) Stable One Tauri binary for every variant โ€” install World Monitor and switch to tech, finance, commodity, energy, or happy in-app. There is deliberately no per-variant download

Issues filed against any of the above are triaged from the same backlog โ€” see the issues board for currently-open work.

Quick Start

bash
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
npm install
npm run dev

Open localhost:3000 (override the port with DEV_PORT in .env.local). The app runs with no environment variables.

Feature-specific data sources may require credentials. See .env.example for the full list.

For variant-specific development:

bash
npm run dev:tech       # tech.worldmonitor.app
npm run dev:finance    # finance.worldmonitor.app
npm run dev:commodity  # commodity.worldmonitor.app
npm run dev:happy      # happy.worldmonitor.app
npm run dev:energy     # energy.worldmonitor.app

See the self-hosting guide for deployment options (Vercel, Docker, static).

Tech Stack

Category Technologies
Frontend Vanilla TypeScript, Vite, globe.gl + Three.js, deck.gl + MapLibre GL
Desktop Tauri 2 (Rust) with Node.js sidecar
AI/ML Ollama / Groq / OpenRouter, Transformers.js (browser-side)
API Contracts Protocol Buffers and sebuf HTTP annotations
Deployment Vercel Edge Functions, Railway relay, Tauri, PWA
Caching Redis (Upstash), 3-tier cache, CDN, service worker

Full stack details in the architecture docs.

Programmatic Access

World Monitor is built for agents and scripts as well as browsers:

  • MCP server โ€” https://worldmonitor.app/mcp (Streamable HTTP). Public tools/list; tools/call authenticates with a X-WorldMonitor-Key header or OAuth.

  • REST API โ€” base https://api.worldmonitor.app, described by the OpenAPI spec.

  • CLI โ€” the official worldmonitor npm package (source in cli/):

    sh
    npx worldmonitor tools          # run ad-hoc โ€” list every MCP tool (no key needed)
npm install worldmonitor     # or install the `worldmonitor` (alias `wm`) command
worldmonitor risk IR --api-key wm_xxx

  • SDKs โ€” official zero-dependency client libraries mirroring the CLI: Python worldmonitor-sdk (source in sdk/python/), Ruby worldmonitor (sdk/ruby/), Go github.com/koala73/worldmonitor/sdk/go (sdk/go/). Guide: worldmonitor.app/docs/sdks.

Agent discovery files: llms.txt ยท agent-skills manifest ยท api-catalog. Get an API key at worldmonitor.app/pro.

Flight Data

Flight data provided graciously by Wingbits, the most advanced ADS-B flight data solution.

Data Sources

WorldMonitor aggregates attributed upstream sources across geopolitics, finance, energy, climate, aviation, cyber, military, infrastructure, and news intelligence. Curated feeds and freshness-tracked source groups are published in the full data sources catalog, with provider, feed-tier, license-posture, and collection-method details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

bash
npm run typecheck        # Type checking
npm run build:full       # Production build

License

AGPL-3.0-only for the source code. Commercial use is permitted under the AGPL when you comply with its copyleft and source-availability terms.

Use Case Allowed?
Personal / research / educational Yes, under AGPL-3.0-only
Self-hosted instance Yes, under AGPL-3.0-only
Fork and modify Yes, share source under AGPL-3.0-only when required
Commercial use / SaaS Yes, under AGPL-3.0-only when you comply with AGPL obligations
Private-source proprietary use or official branding rights Separate commercial or trademark permission needed

See LICENSE for the full code license and docs/license.mdx for a plain-language summary. Commercial licensing is available as an alternative option for teams that need non-AGPL terms.

Copyright (C) 2024-2026 Elie Habib. All rights reserved.

Author

Elie Habib โ€” GitHub

Contributors

Security Acknowledgments

We thank the following researchers for responsibly disclosing security issues:

  • Cody Richard โ€” Disclosed three security findings covering IPC command exposure, renderer-to-sidecar trust boundary analysis, and fetch patch credential injection architecture (2026)

See our Security Policy for responsible disclosure guidelines.

Star History

File: docs/COMMUNITY-PROMOTION-GUIDE.md

World Monitor โ€” Community Promotion Guide

Thank you for helping spread the word about World Monitor! This guide provides talking points, must-see features, and visual suggestions to help you create compelling content for your audience.

What is World Monitor?

One-line pitch: A free, open-source, real-time global intelligence dashboard โ€” like Bloomberg Terminal meets OSINT, for everyone.

Longer description: World Monitor aggregates curated news feeds, military tracking, financial markets, conflict data, protest monitoring, satellite imagery, and AI-powered analysis into a single unified dashboard with an interactive globe. Available as a web app, desktop app (macOS/Windows/Linux), and installable PWA.

Key URLs

Link Description
worldmonitor.app Main dashboard โ€” geopolitics, military, conflicts
tech.worldmonitor.app Tech variant โ€” startups, AI/ML, cybersecurity
finance.worldmonitor.app Finance variant โ€” markets, exchanges, central banks
commodity.worldmonitor.app Commodity variant โ€” mining, metals, energy, supply chains
happy.worldmonitor.app Happy variant โ€” positive news, breakthroughs, conservation
energy.worldmonitor.app Energy variant โ€” oil, gas, chokepoints, energy security
GitHub Source code (AGPL-3.0)

Must-See Features (Top 10)

1. Interactive Globe with a Registry-Backed Layer Catalog

The centerpiece. A WebGL-accelerated globe (deck.gl) with toggleable layers for conflicts, military bases, nuclear facilities, undersea cables, pipelines, satellite fires, protests, cyber threats, and more. Zoom in and the detail layers progressively reveal.

Show: Toggle different layers on/off. Zoom into a conflict region. Show the layer panel.

2. AI-Powered World Brief

One-click AI summary of the top global developments. Three-tier LLM provider chain: local Ollama/LM Studio (fully private, offline), Groq (fast cloud), or OpenRouter (fallback). Redis caching for instant responses on repeat queries.

Show: The summary card at the top of the news panel.

3. Country Intelligence Dossiers

Click any country on the map for a full-page intelligence brief: instability score ring, AI-generated analysis, top headlines, prediction markets, 7-day event timeline, active signal chips, infrastructure exposure, and stock market data.

Show: Click a country (e.g., Japan, Ukraine, or Iran) โ†’ full dossier page.

4. Multilingual Support

The UI follows the runtime locale registry, including Japanese, Swahili, and right-to-left bundles. Regional news feeds auto-adapt โ€” Japanese users see NHK World, Nikkei Asia, and Japan-relevant sources. Language bundles are lazy-loaded for fast performance.

Show: Switch language to Japanese in the settings. Note how feeds change.

5. Live Military Tracking

Real-time ADS-B military flight tracking and AIS naval vessel monitoring. Strategic Posture panel shows theater-level risk assessment across 9 global regions (Baltic, Black Sea, South China Sea, Eastern Mediterranean, etc.).

Show: Enable the Military layer. Show the Strategic Posture panel.

6. Variant Dashboards

One codebase, specialized views โ€” switch between World (geopolitics), Tech (startups/AI), Finance (markets/exchanges), Commodity (resources/supply chains), Happy (positive global trends), and Energy (energy security) with one click in the header bar.

Show: Click the variant switcher and cycle through World, Tech, Finance, Commodity, Happy, and Energy.

7. Market & Crypto Intelligence

7-signal macro radar with composite BUY/CASH verdict, BTC spot ETF flow tracker, stablecoin peg monitor, Fear & Greed Index, and Bitcoin technical indicators. Sparkline charts and donut gauges for visual trends.

Show: Scroll to the crypto/market panels. Point out the sparklines.

8. Live Video & Webcam Feeds

Registry-backed live news streams and webcams from geopolitical hotspots across regions. Idle-aware โ€” auto-pauses after 5 minutes of inactivity.

Show: Open the video panel or webcam panel.

9. Desktop Application (Free)

Native app for macOS, Windows, and Linux via Tauri. API keys stored in OS keychain (not plaintext). The local Node.js sidecar runs the supported API handler catalog offline-capable. Run local LLMs for fully private, offline AI summaries.

Show: The download buttons on the site, or the desktop app running natively.

10. Story Sharing & Social Export

Generate intelligence briefs for any country and share to Twitter/X, LinkedIn, WhatsApp, Telegram, Reddit. Includes canvas-rendered PNG images with QR codes linking back to the live dashboard.

Show: Generate a story for a country โ†’ share dialog with platform options.

11. Local LLM Support (Ollama / LM Studio)

Run AI summarization entirely on your own hardware โ€” no API keys, no cloud, no data leaving your machine. The desktop app auto-discovers models from Ollama or LM Studio, with a three-tier fallback chain: local โ†’ Groq โ†’ OpenRouter. Settings are split into dedicated LLMs and API Keys tabs for easy configuration.

Show: Open Settings โ†’ LLMs tab โ†’ Ollama model dropdown auto-populated โ†’ generate a summary with the local model.

Visual Content Suggestions

Screenshots Worth Taking

  1. Full dashboard overview โ€” globe in center, panels on sides, news feed visible
  2. Country dossier page โ€” click Japan or a hotspot country, show the full brief
  3. Layer toggle demo โ€” before/after with conflicts + military bases enabled
  4. Finance variant โ€” stock exchanges, financial centers, market panels
  5. Japanese UI โ€” show the language switcher and Japanese interface
  6. Webcam grid โ€” live feeds from different regions
  7. Strategic Posture โ€” theater risk levels panel
  8. Settings LLMs tab โ€” Ollama model dropdown with local models discovered

Video/GIF Ideas

  1. 30-second tour: Open site โ†’ rotate globe โ†’ toggle layers โ†’ click country โ†’ show brief
  2. Language switch: English โ†’ Japanese, show how feeds adapt
  3. Layer stacking: Start empty โ†’ add conflicts โ†’ military โ†’ cyber โ†’ fires โ†’ wow
  4. Variant switching: World โ†’ Tech โ†’ Finance in quick succession

Talking Points for Posts

For General Audience

  • "An open-source Bloomberg Terminal for everyone โ€” free, no login required"
  • "Curated news sources, military tracking, AI analysis โ€” all in one dashboard"
  • "Run AI summaries locally with Ollama โ€” your data never leaves your machine"
  • "Available in Japanese with NHK and Nikkei feeds built in"
  • "Native desktop app for macOS/Windows/Linux, completely free"

For Tech Audience

  • "Built with TypeScript, Vite, deck.gl, MapLibre GL, Tauri"
  • "A registry-backed WebGL map layer catalog"
  • "ONNX Runtime Web for browser-based ML inference (sentiment, NER, summarization)"
  • "Local LLM support โ€” plug in Ollama or LM Studio, zero cloud dependency"
  • "Open source under AGPL-3.0 โ€” contribute on GitHub"

For Finance/OSINT Audience

  • "7-signal crypto macro radar with BUY/CASH composite verdict"
  • "Global stock exchanges mapped with market caps and trading hours"
  • "Country Instability Index tracking 31 Tier-1 countries in real time"
  • "Prediction market integration for geopolitical forecasting"
  • "Air-gapped AI analysis โ€” run Ollama locally for sensitive intelligence work"

For Japanese Audience Specifically

  • ๆ—ฅๆœฌ่ชžๅฎŒๅ…จๅฏพๅฟœ โ€” UIใ€ใƒ‹ใƒฅใƒผใ‚นใƒ•ใ‚ฃใƒผใƒ‰ใ€AI่ฆ็ด„ใ™ในใฆๆ—ฅๆœฌ่ชžใงๅˆฉ็”จๅฏ่ƒฝ
  • NHK Worldใ€ๆ—ฅ็ตŒใ‚ขใ‚ธใ‚ขใชใฉๆ—ฅๆœฌๅ‘ใ‘ใƒ‹ใƒฅใƒผใ‚นใ‚ฝใƒผใ‚นๅ†…่”ต
  • ็„กๆ–™ใƒปใ‚ชใƒผใƒ—ใƒณใ‚ฝใƒผใ‚น โ€” ใ‚ขใ‚ซใ‚ฆใƒณใƒˆ็™ป้Œฒไธ่ฆ
  • macOS/Windows/Linuxๅฏพๅฟœใฎใƒ‡ใ‚นใ‚ฏใƒˆใƒƒใƒ—ใ‚ขใƒ—ใƒชใ‚ใ‚Š

Recent Major Features (Changelog Highlights)

Version Feature
v2.5.1 Batch FRED fetching, parallel UCDP, partial cache TTL, bot middleware
v2.5.0 Ollama/LM Studio local LLM support, settings split into LLMs + API Keys tabs, keychain vault consolidation
v2.4.1 Ultra-wide layout (panels wrap around map on 2000px+ screens)
v2.4.0 Live webcams from 19 geopolitical hotspots, 4 regions
v2.3.9 Full i18n foundation; introduced Japanese, Arabic (RTL), Chinese, and other localized interfaces
v2.3.8 Finance variant with exchange coverage, Gulf FDI investments
v2.3.7 Light/dark theme system, UCDP/UNHCR/Climate panels
v2.3.6 Desktop app with Tauri, OS keychain, auto-updates
v2.3.0 Country Intelligence dossiers, story sharing

Branding Notes

  • Name: "World Monitor" (two words, capitalized)
  • Tagline: "Real-time global intelligence dashboard"
  • License: AGPL-3.0 (free and open source)
  • Creator: Credit "World Monitor by Elie Habib" or link to the GitHub repo
  • Variants: You can mention all six (World/Tech/Finance/Commodity/Happy/Energy) or focus on the main one
  • No login required: Anyone can use the web app immediately โ€” no signup, no paywall

Thank You

We genuinely appreciate community members helping grow World Monitor's reach. Feel free to interpret these guidelines creatively โ€” there's no strict template. The most compelling content comes from showing what YOU find most interesting or useful about the tool.

If you have questions or want specific screenshots/assets, open a Discussion on the GitHub repo or reach out directly.

File: docs/local-backend-audit.md

Local backend parity matrix (desktop sidecar)

This matrix tracks desktop parity by mapping src/services/*.ts consumers to sebuf domain handlers and classifying each feature as:

  • Fully local: works from desktop sidecar without user credentials.
  • Requires user-provided API key: local endpoint exists, but capability depends on configured secrets.
  • Requires cloud fallback: sidecar exists, but operational behavior depends on a cloud relay path.

Architecture

All JSON API endpoints now use sebuf-generated handlers served through a single catch-all gateway (api/[[...path]].js). Handler implementations live in server/worldmonitor/{domain}/v1/. The desktop sidecar runs the same handler code locally via an esbuild-compiled bundle.

Remaining non-sebuf api/*.js files serve non-JSON content (RSS XML, HTML, redirects) and are not part of this matrix.

Priority closure order

  1. Priority 1 (core panels + map): LiveNewsPanel, MonitorPanel, StrategicRiskPanel, critical map layers.
  2. Priority 2 (intelligence continuity): summaries and market panel.
  3. Priority 3 (enhancements): enrichment and relay-dependent tracking extras.

Feature parity matrix

Priority Feature / Panel Service source(s) Sebuf domain Handler path Classification Closure status
P1 LiveNewsPanel src/services/live-news.ts Non-sebuf (YouTube) api/youtube/live.js Fully local โœ… Local endpoint available; channel-level video fallback already implemented.
P1 MonitorPanel None (panel-local keyword matching) None None Fully local โœ… Client-side only (no backend dependency).
P1 StrategicRiskPanel cached overlays src/services/cached-risk-scores.ts intelligence server/worldmonitor/intelligence/v1/ Requires user-provided API key โœ… Explicit fallback: panel continues with local aggregate scoring when cache feed is unavailable.
P1 Map layers (conflicts, outages, AIS, military flights) src/services/conflict/, src/services/infrastructure/, src/services/maritime/, src/services/military/ conflict, infrastructure, maritime, military server/worldmonitor/{domain}/v1/ Requires user-provided API key โœ… Explicit fallback: unavailable feeds are disabled while map rendering remains active for local/static layers.
P2 Summaries src/services/news/ news server/worldmonitor/news/v1/ Requires user-provided API key โœ… Explicit fallback chain: Groq โ†’ OpenRouter โ†’ browser model.
P2 MarketPanel src/services/market/, src/services/prediction/ market, prediction server/worldmonitor/market/v1/, server/worldmonitor/prediction/v1/ Fully local โœ… Multi-provider and cache-aware fetch behavior maintained in sidecar mode.
P3 Flight enrichment src/services/military/ military server/worldmonitor/military/v1/ Requires user-provided API key โœ… Explicit fallback: heuristic-only classification mode.
P3 OpenSky relay fallback path src/services/military/ military server/worldmonitor/military/v1/ Requires cloud fallback โœ… Relay fallback documented; no hard failure when relay is unavailable.

Non-parity closure actions completed

  • Added desktop readiness + non-parity fallback visibility in ServiceStatusPanel so operators can see acceptance status and per-feature fallback behavior in desktop runtime.
  • Kept local-sidecar strategy as the default path: desktop sidecar executes sebuf handlers locally via the esbuild-compiled bundle and only uses cloud fallback when handler execution or relay path fails.

Desktop-ready acceptance criteria

A desktop build is considered ready when all checks below are green:

  1. Startup: app launches and local sidecar health reports enabled.
  2. Map rendering: map loads with local/static layers even when optional feeds are unavailable.
  3. Core intelligence panels: LiveNewsPanel, MonitorPanel, StrategicRiskPanel render without fatal errors.
  4. Summaries: at least one summary path works (provider-backed or browser fallback).
  5. Market panel: panel renders and returns data from at least one market provider.
  6. Live tracking: at least one live mode (AIS or OpenSky) is available.

These checks are now surfaced in the Service Status UI as "Desktop readiness".

File: docs/TAURI_VALIDATION_REPORT.md

Tauri Validation Report

Scope

Validated desktop build readiness for the World Monitor Tauri app by checking frontend compilation, TypeScript integrity, and Tauri/Rust build execution.

Preflight checks before desktop validation

Run these checks first so failures are classified quickly:

  1. npm registry reachability
    • npm ping
  2. crates.io sparse index reachability
    • curl -I https://index.crates.io/
  3. proxy configuration present when required by your network
    • env | grep -E '^(HTTP_PROXY|HTTPS_PROXY|NO_PROXY)='

If any of these checks fail, treat downstream desktop build failures as environment-level until the network path is fixed.

Commands run

  1. npm ci โ€” failed because the environment blocks downloading the pinned @tauri-apps/cli package from npm (403 Forbidden).
  2. npm run typecheck โ€” succeeded.
  3. npm run build:full โ€” succeeded (warnings only).
  4. npm run desktop:tauri:build โ€” not runnable in this environment because npm ci failed, so the local tauri binary was unavailable (desktop scripts now fail fast with a clear npm ci remediation message when this occurs).
  5. cargo check (from src-tauri/) โ€” failed because the environment blocks downloading crates from https://index.crates.io (403 CONNECT tunnel failed).

Assessment

  • The web app portion compiles successfully.
  • Full Tauri desktop validation in this run is blocked by an external environment outage/restriction (registry access denied with HTTP 403).
  • No code/runtime defects were observed in project sources during this validation pass.

Failure classification for future QA

Use these labels in future reports so outcomes are actionable:

  1. External environment outage

    • Symptoms: npm/crates registry requests fail with transport/auth/network errors (403/5xx/timeout/DNS/proxy), independent of repository state.
    • Action: retry in a healthy network or fix credentials/proxy/mirror availability.

  2. Expected failure: offline mode not provisioned

    • Symptoms: build is intentionally run without internet, but required offline inputs are missing (for Rust: no vendor/ artifact, no internal mirror mapping, or offline override not enabled; for JS: no prepared package cache).
    • Action: provision offline artifacts/mirror config first, enable offline override (config.local.toml or CLI --config), then rerun.

Next action to validate desktop end-to-end

Choose one supported path:

  • Online path:

    • npm ci
    • npm run desktop:tauri:build

  • Restricted-network path:

    • Restore prebuilt offline artifacts (including src-tauri/vendor/ or internal mirror mapping).
    • Run Cargo with source.crates-io.replace-with mapped to vendored/internal source and --offline where applicable.

After npm ci, desktop build uses the local tauri binary and does not rely on runtime npx package retrieval.

Remediation options for restricted environments

If preflight fails, use one of these approved remediations:

  • Configure an internal npm mirror/proxy for Node packages.
  • Configure an internal Cargo registry/sparse index mirror for Rust crates.
  • Pre-vendor Rust crates (src-tauri/vendor/) and run Cargo in offline mode.
  • Use CI runners that restore package/cache artifacts from a trusted internal store before builds.

For release packaging details, see docs/release-packaging.mdx (section: Network preflight and remediation).

2. Official Technical Reference & Guides (koala73/docs)

Mintlify Starter Kit

Use the starter kit to get your docs deployed and ready to customize.

Click the green Use this template button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with

  • Guide pages
  • Navigation
  • Customizations
  • API reference pages
  • Use of popular components

Follow the full quickstart guide

AI-assisted writing

Set up your AI coding tool to work with Mintlify:

bash
npx skills add https://mintlify.com/docs

This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.

See the AI tools guides for tool-specific setup.

Development

Install the Mintlify CLI to preview your documentation changes locally. To install, use the following command:

text
npm i mint

Run the following command at the root of your documentation, where your docs.json is located:

text
mint dev

View your local preview at http://localhost:3000.

Publishing changes

Install our GitHub app from your dashboard to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.

Need help?

Troubleshooting

  • If your dev environment isn't running: Run mint update to ensure you have the most recent version of the CLI.
  • If a page loads as a 404: Make sure you are running in a folder with a valid docs.json.

Resources

Explore Related Technologies & Topics

View All 9,111+ Repositories โ†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agent Browse agent catalog โ†’ #ai Browse ai catalog โ†’ #dashboard Browse dashboard catalog โ†’ #geopolitics Browse geopolitics catalog โ†’ #mcp Browse mcp catalog โ†’ #mcp-server Browse mcp-server catalog โ†’ โšก MCP Servers Model Context Protocol โ†’ ๐Ÿง  Agent Skills Prompt & rule files โ†’ ๐Ÿ”Œ OpenAPI Specs REST & Swagger schemas โ†’