Skip to main content
Part of the Architecture and Design Philosophy guide, which indexes every topic. For deployment topology, directory layout and CI/CD, see ARCHITECTURE.md.

​
Railway Seed Data Pipeline

Railway cron services continuously refresh the Redis cache with pre-computed data from external APIs. A row below is a seed script, not a separate cron job: bundled services run several seeds on one schedule (for example, the displacement and border seeders all run inside seed-bundle-health). Seeds run on configurable schedules from minutes to daily cadence and write both a canonical domain key (for RPC handler lookups) and a bootstrap key (for page-load hydration). This dual-key strategy ensures that bootstrap hydration and RPC handlers always agree on data format and freshness. Seeds use cachedFetchJson with in-flight promise coalescing — if a seed run overlaps with a previous run still writing, the concurrent write is deduplicated. Each seed script is self-contained (single .mjs file, no build step), runs on Node.js 20+, and connects to Upstash Redis via REST API. Failed seed runs log errors but never corrupt existing cached data — the previous cache entry persists until a successful run replaces it.

​
Edge Functions & Deployment

​
Edge Function Architecture

World Monitor uses Vercel Edge Functions as a lightweight API layer, split into two generations. Legacy endpoints in api/*.js each handle a single data source concern — proxying, caching, or transforming external APIs. The newer proto-first endpoints use per-domain thin entry points, each importing only its own handler module. This replaced the original monolithic gateway that loaded every domain on each cold start. Each domain’s function tree-shakes to include only its dependencies, reducing cold-start time by ~85% (sub-100ms for most endpoints vs. 500ms+ with the monolithic handler). A shared server/gateway.ts provides common routing logic. Both generations coexist, with new features built proto-first. This architecture avoids a monolithic backend while keeping API keys server-side:
  • RSS Proxy — domain-allowlisted proxy for the registered feed catalog, preventing CORS issues and hiding origin servers. The Edge proxy and Railway relay both keep redirects manual and re-check the RSS domain allowlist before every hop. Feeds from domains that block Vercel IPs are automatically routed through the Railway relay.
  • AI Pipeline — Ollama and OpenRouter summarization edge functions with Redis deduplication, so identical headlines across concurrent users only trigger one LLM call. The classify-event endpoint pauses its queue on 500 errors to avoid wasting API quota.
  • Data Adapters — GDELT, ACLED, OpenSky, USGS, NASA FIRMS, FRED, Yahoo Finance, CoinGecko, mempool.space, BIS, WTO, and others each have dedicated edge functions that normalize responses into consistent schemas
  • Market Intelligence — macro signals, ETF flows, and stablecoin monitors compute derived analytics server-side (VWAP, SMA, peg deviation, flow estimates) and cache results in Redis
  • Temporal Baseline — Welford’s algorithm state is persisted in Redis across requests, building statistical baselines without a traditional database
  • Custom Scrapers — sources without RSS feeds (MIIT news, GitHub Trending, tech events) are scraped and transformed into RSS-compatible formats
  • Finance Geo Data — stock exchanges, financial centers, central-bank and supranational finance institutions, and commodity hubs are served as static typed datasets with market caps, GFCI rankings, trading hours, and commodity specializations
  • BIS Integration — policy rates, real effective exchange rates, and credit-to-GDP ratios from the Bank for International Settlements, cached with 30-minute TTL
  • WTO Trade Policy — trade restrictions, tariff trends, bilateral trade flows, and SPS/TBT barriers from the World Trade Organization
  • Supply Chain Intelligence — maritime chokepoint disruption scores (cross-referencing NGA warnings + AIS data), FRED shipping freight indices with spike detection, and critical mineral supply concentration via Herfindahl-Hirschman Index analysis
  • Corporate Intelligence — IntelligenceService.GetCompanyEnrichment resolves a company through the SEC’s ticker→CIK registry (seeded daily from company_tickers.json) and aggregates EDGAR identity plus recent filings (10-K, 10-Q, 8-K with item codes), Finnhub market profile and earnings surprises, and recent news mentions into one envelope. IntelligenceService.ListCompanySignals classifies timestamped signals from SEC 8-K material events (tier 1) and news mentions (tier 3); Finnhub fiscal period ends stay in enrichment rather than being mislabeled as report timestamps. SearchSecFilings proxies EDGAR full-text search; ListMaterialEvents serves a seeded market-wide stream of material 8-K filings. No guessed attribution: companies that do not resolve in the SEC registry return empty envelopes (see issues #3754/#3755 for the heuristic predecessor this replaced)
All edge functions include circuit breaker logic and return cached stale data when upstream APIs are unavailable, ensuring the dashboard never shows blank panels.

​
Cold-Start Optimization — Per-Domain Edge Function Split

The original monolithic edge gateway (api/[domain]/v1/[rpc].ts) imported every service domain handler into a single function. When any RPC was called, the edge runtime loaded the entire handler graph — initializing Redis clients, parsing configuration, and importing utility modules for every domain even though only 1 was needed. This was split into per-domain thin entry points — one per service domain — each importing only its own handler module. The shared gateway (server/gateway.ts) provides common routing logic, but each domain’s edge function tree-shakes to include only its dependencies. Impact: Cold-start time dropped by ~85% — a market quote request no longer loads the cyber threat intelligence parser, the OREF alert handler, or the climate anomaly detector. On Vercel’s edge runtime, this translates to sub-100ms cold starts for most endpoints, compared to 500ms+ with the monolithic handler.

​
Single-Deployment Variant Consolidation

All published dashboard variants serve from a single Vercel deployment. The variant is determined at runtime by hostname detection: On the desktop app, the variant is stored in localStorage['worldmonitor-variant'] and can be switched without rebuilding. The variant selector in the header bar navigates between deployed domains on the web or toggles the localStorage value on desktop. This architecture replaced the original multi-deployment approach (separate Vercel projects per variant) and provides several advantages:
  • Instant switching — users toggle variants in the header bar without a full page navigation or DNS lookup
  • Shared CDN cache — the static SPA assets are identical across variants; only runtime configuration differs. CDN cache hit rates are 4× higher than with separate deployments
  • Single CI pipeline — one build, one deployment, one set of edge functions. No cross-deployment configuration drift
  • Social bot routing — the OG image endpoint generates variant-specific preview cards based on the requesting hostname, so sharing a Tech Monitor link produces tech-branded social previews