Atlas 🌍

Real-time global situational-awareness console — country risk, cross-stream signals, markets and world news on a GPU-rendered globe. Built entirely on free, keyless, open data and deployed as a zero-config Next.js app on Vercel.

Live: https://atlas-eight-fawn.vercel.app

Dark	Light

Stack

• Next.js 16 (App Router) + React 19 + TypeScript (strict, noUncheckedIndexedAccess)
• Tailwind CSS v4 — colour system v2 (docs/colour-system-v2.md): cool slate ground, blue = interactive, a 5-step warm severity ramp for risk (red only for the worst), per-layer category hues; Archivo, 0 radius, JetBrains Mono telemetry, glass map overlays
• MapLibre GL v5 + deck.gl 9 — one WebGL context: native feature-state choropleth for risk, deck.gl layers interleaved on the globe (MapLibre v6 drops the map.transform API deck.gl's overlay needs, so v5 is pinned until deck.gl supports it)
• Zustand — control state (layers, filters, camera, selection, telemetry) with debounced two-way URL sync for shareable deep links
• TanStack Query — polling that pauses in background tabs, exponential backoff, last-good-data retention
• Vitest — unit tests for the whole server data pipeline · Playwright — production smoke tests in CI

Data sources (all free)

Source	Used for	Key	Terms
Publisher RSS (The Hindu, NDTV, TOI, Mint, ET, BBC, Al Jazeera, DW, France 24, Guardian, NPR, UN News)	News backbone, subject-country tagging	none	Headlines + links only, per publisher terms
GDELT DOC 2.0	Supplementary world news + tone (throttled to 1 req / 5 s per IP, so best-effort)	none	Open use with citation
Yahoo Finance chart API	India + global markets	none	Unofficial endpoint, Yahoo terms
Alpha Vantage	Top gainer (and per-article news sentiment on a premium plan; free keys get "premium endpoint" for that). Free tier is 25 requests/day and 1/second, so calls are spaced apart and cached for 3 h	optional ALPHA_VANTAGE_API_KEY	Free tier terms
Groq / OpenRouter (openrouter/free)	AI briefs, deterministic fallback otherwise	optional GROQ_API_KEY / OPENROUTER_API_KEY	Provider terms
OpenFreeMap (OSM) · CARTO fallback	Vector basemaps	none	ODbL (OSM data), attribution shown on map
USGS real-time feed	Earthquakes M2.5+ (browser-direct, CORS-open)	none	U.S. public domain
NASA EONET · GDACS	Natural events + disaster impact alerts (via /api/hazards)	none	NASA open data · GDACS free use with attribution
adsb.lol	Live aircraft in the visible area (via /api/flights)	none	ODbL
IODA (Georgia Tech) · abuse.ch Feodo Tracker	Internet outages by country, botnet C2 hosting (via /api/cyber)	none	IODA terms · CC0
TfL JamCams	London traffic-camera stills (via /api/cctv)	none	Open Government Licence ("Powered by TfL Open Data")
YouTube live embeds	24/7 news channels (privacy-enhanced youtube-nocookie)	none	YouTube terms
U.S. EIA · Lloyd's List · ICG CrisisWatch	Static reference: chokepoints, major ports, flashpoint areas	none

Architecture

flowchart LR
  subgraph Browser
    UI["Console (React 19)<br/>HUD · intel panel · inspector"]
    Store["Zustand store<br/>⇄ URL deep link"]
    Q["TanStack Query<br/>polling · backoff · persisted cache"]
    Map["MapLibre globe + deck.gl overlay<br/>(lazy chunk)"]
    UI <--> Store
    UI --> Q
    Store --> Map
    Q --> Map
  end

  subgraph Vercel["Vercel (Next.js route handlers, CDN-cached)"]
    Metrics["/api/metrics<br/>RSS · GDELT · markets → risk, signals"]
    Live["/api/hazards · cyber · flights · cctv<br/>per-source timeouts, coalescing"]
    Brief["/api/brief<br/>validated · LRU · rate-limited"]
  end

  Q -->|"s-maxage + swr"| Metrics
  Q --> Live
  UI -->|shared keys| Brief
  Q -->|CORS-open| USGS[(USGS quakes)]
  UI -->|BYOK, key stays in browser| LLM[(Groq / OpenRouter)]
  Brief --> LLM
  Metrics --> Up[(Publisher RSS · GDELT · Yahoo · Alpha Vantage)]
  Live --> Up2[(EONET · GDACS · adsb.lol · IODA · Feodo · TfL)]

app/
  page.tsx               static shell → <Console/> (client)
  api/metrics/route.ts   aggregated payload; CDN cached (s-maxage=60, swr=300)
  api/briefing/route.ts  AI "Today's briefing", served apart from /api/metrics so a slow free model never delays it;
                         30 min per-headline-set cache, rule-based digest until it arrives
  api/brief/route.ts     AI brief on shared free-tier keys: validated input, 15 min LRU, 8 req/min/IP
  api/{hazards,cyber,cctv,flights}/route.ts
                         live-layer proxies: per-source timeouts, in-instance coalescing,
                         CDN s-maxage tuned per feed (10 s flights … 1 h cameras)
  api/health/route.ts
src/
  server/                data pipeline: fetchers (all via fetchWithTimeout), RSS parser,
                         country gazetteer, risk index, signals, sentiment, LLM chain, TTL cache
  state/                 Zustand store + typed contracts + URL sync
  layers/                registry (label, hotkey, method, source) → dock/palette/help;
                         pure upstream parsers → normalized GeoItem; useLiveLayers queries
  map/                   MapCanvas (dynamic import, ssr: false), deck.gl layer factories, geometry
  components/hud/        top bar, layer dock, tabbed intel panel / mobile sheet, status rail, palette
  components/modules/    risk index, signals, markets, news feed, briefs
  types/metrics.ts       wire contract shared by server and client

Resilience: every upstream self-falls-back; the route coalesces concurrent cold requests into one fetch, serves the last good payload on failure, and keeps the last real news feed if a refresh comes back empty.

Console

• Full-bleed globe with a floating layer dock (live entity counts, status, opacity), a docked intel panel (Intel · Markets · News · Brief), and a status rail showing which sources contributed to the current refresh, API latency and a headline tape.
• News Mood is computed from headline wording (a transparent positive/negative word list with negation, src/server/headlineSentiment.ts), because per-article news sentiment is a premium Alpha Vantage feature. The tile, gauge and chips say how the number was produced; an Alpha Vantage premium key is used automatically when present.
• Nine layers in five groups: regional risk, live news, earthquakes, disasters, aircraft, internet outages, chokepoints & ports, traffic cameras, live TV. Disaster markers share one hue and show the kind of event by style (solid = fire / heat, ring = water / storm, soft = ground / other), and the layer dock warns when one source behind a layer (say GDACS) is down. The Intel tab lists the newest CISA Known Exploited Vulnerabilities while the internet-outage layer is on. Each fetches only while it's on, polls at a cadence matched to its source, pauses in background tabs, and reports status/count/errors to the dock. Small slow-moving layers persist to localStorage and repaint instantly on reload.
• Aircraft are fetched for the visible box only (zoom ≥ 4, 2°-quantized so pans share cache keys) and drawn radar-style: a dot at barometric altitude plus a heading tail scaled to ground speed.
• Click a camera or TV marker for a floating viewer (map stays interactive). Click anything else, pick a country, or press G and click any point to open the inspector. It shows facts and the source link, the country found by point-in-polygon on the loaded geometry, events within 500 km by great-circle distance, a coverage/event timeline, and the latest matching headlines.
• AI situational brief on demand. It's generated only from the facts and headlines the inspector shows: the prompt forbids outside knowledge and treats headline text as data. It uses Atlas's shared free-tier keys through /api/brief (input validation, LRU cache, per-IP rate limit, rule-based fallback). With bring your own key, the browser calls Groq or OpenRouter directly (both allow CORS), so the key stays in localStorage and never reaches Atlas's server.
• Radar pings on the busiest news hotspots are MapLibre DOM markers animated purely in CSS (compositor thread, zero per-frame JS, off under prefers-reduced-motion).
• Rendering notes: deck.gl primitives are lifted 3 km off the globe so they don't z-fight with MapLibre's sphere, and aircraft tails use PathLayer because LineLayer doesn't draw under the globe projection.

Quality gates

Every push and PR runs ci.yml (audit gate → typecheck → lint → Vitest → build → initial-JS budget → Playwright smoke) and security.yml (gitleaks + Semgrep).

• Initial JS budget: npm run size sums the gzip size of every script the prerendered page loads (skipping noModule polyfills, which modern browsers never fetch) and fails above 180 kB. Currently ~165 kB; MapLibre, deck.gl, the inspector, palette, help, media viewer and asset drawer are all lazy chunks.
• Vitest route tests (src/**/*.test.ts): 234 unit + integration tests covering the full server data pipeline, all six API routes (/api/health, /api/metrics, /api/hazards, /api/cyber, /api/flights, /api/cctv), headline sentiment, URL sync, LLM chain, and rate-limit logic.
• Playwright smoke (e2e/): health endpoint, shell renders with no uncaught errors and the WebGL globe mounts (SwiftShader on CI), URL deep link ⇄ layer toggles, and the lazily loaded ⌘K palette.
• Contrast guard: e2e/a11y.spec.ts runs axe color-contrast (WCAG AA) in light and dark over every intel tab, the layer dock, inspector, ⌘K palette, help overlay and a mobile viewport. Colour is semantic (blue --accent = interactive, --sev-1..5 = severity, --cat-* = layer kind) and every token pair is checked by axe.
• Lighthouse (local production build, desktop preset): Accessibility 95 · Best Practices 100 · SEO 100 · CLS 0 (desktop and mobile). The performance score is dominated by the WebGL globe, which headless Lighthouse renders on the CPU (SwiftShader), so it says little about real GPUs.
• Layout stability: the top-signal row and threat chip reserve their space before data arrives, so the map doesn't jump on load (CLS was 0.32 before).

Security

Strict CSP and hardening headers on every response, secret scanning, Semgrep, weekly Dependabot with a one-week cooldown, and a CI npm audit gate. One accepted advisory (maplibre-gl, not reachable here) is documented with a review date in SECURITY.md.

License

MIT © 2026 Rishabh Verma. Data sources keep their own terms (see the table above).

Develop

npm install
cp .env.example .env.local   # optional keys
npm run dev                  # http://localhost:3000
npm run typecheck && npm run lint && npm test && npm run build
npm run size                 # initial JS budget (after build)
npm run audit:gate           # npm audit, minus documented accepted risks
npx playwright install chromium --only-shell
npm run test:e2e             # smoke tests against `next start`

Feature concepts adapted from koala73/worldmonitor (AGPL-3.0) — ideas only, no code copied.