WarWatch

Geopolitics tracker prototype: a React + React Three Fiber globe UI and a Node/Express backend that broadcasts realtime updates over WebSockets.

Prereqs

• Node.js 20+ (you have Node v24)
• npm

Setup

1. Create .env from .env.example (optional for now)
2. Install deps:
   • npm install
3. (Optional) Create client/.env to set VITE_NEWS_QUERY="your query" for the conflict search card.

If npm install fails with certificate/proxy errors (SELF_SIGNED_CERT_IN_CHAIN / HTML responses), your network is intercepting npm traffic. Fix by installing your org root CA (preferred) or configuring npm cafile/proxy. A temporary repo-local workaround is .npmrc with strict-ssl=false (already present) but it is not recommended long-term.

Run

Client: Vite dev server prints the URL. Server: http://localhost:8787

Maps mode (OpenMapTiles)

Maps mode renders a single globe texture built from raster tiles. To use OpenMapTiles (typically via tileserver-gl), configure a raster tile URL template.

• Recommended (avoids CORS/tainted-canvas issues): proxy tiles through the WarWatch server.

  • Server env:
    • TILE_RASTER_URL_TEMPLATE=http://localhost:8080/styles/osm-bright/{z}/{x}/{y}.png
  • Client env:
    • VITE_MAP_RASTER_TILE_TEMPLATE=/api/tiles/{z}/{x}/{y}.png
    • VITE_MAP_RASTER_ZOOM=4 (try 5 if your machine can handle it)

• Direct (only works if your tile server sets permissive CORS headers):

  • VITE_MAP_RASTER_TILE_TEMPLATE=http://localhost:8080/styles/osm-bright/{z}/{x}/{y}.png

What’s implemented

• NewsAPI adapter (server-side; uses NEWSAPI_KEY when set, otherwise emits mock items)
• NewsAPI query endpoint + conflict search UI (/api/news/query) that lets you pull topic-specific headlines.
  • Set NEWSAPI_INSECURE_TLS=true if your network intercepts TLS (similar to OPENSKY_INSECURE_TLS).
• Default News feed polling uses NewsAPI everything with a war/geopolitics-focused query.
  • Override with NEWSAPI_POLL_QUERY, and optionally restrict with NEWSAPI_SOURCES or NEWSAPI_DOMAINS.
• Flight tracking via OpenSky (default, free-ish) and a FlightRadar-compatible adapter (optional)
• Provider stubs for X (to implement later)
• UI: conflicts list, death toll meter, war-risk score, AI click-to-analyze

AI (LLM)

The backend supports a free, local LLM via Ollama and optionally OpenAI.

• Default: LLM_PROVIDER=ollama
• Requires Ollama running locally at OLLAMA_URL (default http://127.0.0.1:11434) and a pulled model (default OLLAMA_MODEL=llama3.1).

Flight data providers

• Default: FLIGHTS_PROVIDER=opensky (calls OpenSky state vectors)
• Recommended fallback: FLIGHTS_PROVIDER=adsblol (uses api.adsb.lol and requires a center point + radius)
• Optional: FLIGHTS_PROVIDER=flightradar (uses FLIGHTRADAR_API_URL adapter)
• If your network injects intercepting TLS certificates and OpenSky requests fail with SELF_SIGNED_CERT_IN_CHAIN, set OPENSKY_INSECURE_TLS=true (only for trusted/dev environments).

adsb.lol quick config

• Set FLIGHTS_PROVIDER=adsblol
• Set ADSBLOL_CENTER_LAT, ADSBLOL_CENTER_LON, ADSBLOL_RADIUS_NM (max 250)

News data

• /api/news/query + NEWSAPI_DEFAULT_QUERY lets the UI request topic-specific headlines via NewsAPI's everything endpoint.

Key env vars

• NEWSAPI_KEY - Enables NewsAPI calls (otherwise the server emits mock items).
• GDELT_DOC_SOURCELANG - Language filter applied to GDELT click-through (DOC ArtList) URLs. Defaults to english. Set to all to disable.
• AISSTREAM_API_KEY - If set, the backend connects to AISStream over WebSocket and /api/ships serves a live snapshot (requires AISSTREAM_BBOX or AISSTREAM_BOUNDING_BOXES).
• SHIPS_API_URL - Optional fallback. If set (and AISStream is not configured), /api/ships pulls ship tracks from this JSON endpoint (see .env.example for shape).