Architecture - World Monitor

Tech Stack

Frontend

Technology	Purpose	Version
TypeScript	Type-safe JavaScript	5.7.2
Vite	Build tool and dev server	6.0.7
MapLibre GL JS	2D/3D map rendering	5.16.0
deck.gl	WebGL data visualization	9.2.6
D3.js	Charts and data transformations	7.9.0
i18next	Internationalization (16 languages)	25.8.10
Vite PWA	Progressive web app features	1.2.0

Backend (Serverless)

Technology	Purpose
Vercel Edge Functions	Serverless API routes
Node.js	Server runtime
Sebuf	TypeScript RPC framework
Upstash Redis	Distributed cache and rate limiting
Convex	Real-time database for registrations

Desktop (Tauri)

Technology	Purpose	Version
Tauri	Native app framework	2.10.0
Rust	Backend runtime	—
Node.js Sidecar	Local API server	18+

AI & ML

Technology	Purpose
Transformers.js	Browser-side ML (NER, sentiment)	2.17.2
ONNX Runtime Web	Neural network inference	1.23.2
Ollama	Local LLM inference	—
Groq	Cloud LLM inference (Llama 3.1 8B)	—
OpenRouter	Multi-model LLM gateway	—

Data Processing

Technology	Purpose
PapaParse	CSV parsing	5.5.3
fast-xml-parser	XML/RSS parsing	5.3.7
topojson-client	TopoJSON mesh rendering	3.1.0
h3-js	Hexagonal spatial indexing	4.4.0

Protobuf Tooling

Tool	Purpose	Version
buf	Proto linting and generation	1.64.0
sebuf	TypeScript RPC code generator	0.7.0
protoc-gen-ts-client	Client stub generator	—
protoc-gen-ts-server	Server handler generator	—
protoc-gen-openapiv3	OpenAPI spec generator	—

System Architecture

High-Level Design

Proto-First API Flow

Desktop Architecture

Project Structure

worldmonitor/
├── api/                          # Vercel serverless functions
│   ├── [domain]/v1/[rpc].ts     # Sebuf RPC gateway catch-all
│   ├── download.ts              # Desktop installer redirect
│   └── og-story.ts              # Dynamic Open Graph images
├── convex/                       # Convex database schema
├── data/                         # Static datasets (GeoJSON, CSV)
├── deploy/                       # Deployment configs
├── docs/                         # Documentation source
│   └── api/                     # Generated OpenAPI specs
├── e2e/                         # Playwright E2E tests
├── proto/                       # Protocol buffer definitions
│   ├── buf.gen.yaml             # Code generation config
│   ├── sebuf/                   # Sebuf framework protos
│   └── worldmonitor/            # Service definitions (20 domains)
│       ├── aviation/v1/
│       ├── climate/v1/
│       ├── conflict/v1/
│       ├── cyber/v1/
│       ├── seismology/v1/
│       └── ...
├── public/                      # Static assets
├── scripts/                     # Build and utility scripts
│   ├── build-sidecar-sebuf.mjs # Bundle sidecar gateway
│   ├── desktop-package.mjs     # Package desktop builds
│   ├── ais-relay.cjs           # Railway relay server
│   └── ...
├── server/                      # Server-side handler implementations
│   ├── router.ts               # HTTP route matcher
│   ├── cors.ts                 # CORS policy
│   ├── error-mapper.ts         # Error response formatter
│   └── worldmonitor/           # Handler implementations
│       ├── seismology/v1/handler.ts
│       ├── aviation/v1/handler.ts
│       └── ...
├── src/                         # Frontend source code
│   ├── App.ts                  # Main application entry
│   ├── main.ts                 # Vite entry point
│   ├── components/             # UI components (panels, modals)
│   ├── services/               # Data fetching services
│   ├── utils/                  # Helper functions
│   ├── config/                 # Configuration files
│   ├── locales/                # i18n translation files (16 languages)
│   ├── workers/                # Web Workers (ML inference)
│   ├── generated/              # Generated code (DO NOT EDIT)
│   │   ├── client/             # TypeScript RPC clients
│   │   └── server/             # TypeScript RPC servers
│   └── styles/                 # Global CSS
├── src-tauri/                   # Tauri desktop app
│   ├── src/                    # Rust source code
│   ├── sidecar/                # Node.js sidecar server
│   └── tauri.conf.json         # Tauri configuration
├── tests/                       # Unit and API tests
├── vite.config.ts              # Vite build configuration
├── playwright.config.ts        # Playwright test configuration
├── tsconfig.json               # TypeScript configuration
├── Makefile                    # Development commands
└── package.json                # npm scripts and dependencies

Key Directories Explained

`/proto`

Contains all protocol buffer definitions organized by domain:

20 service domains: aviation, climate, conflict, cyber, displacement, economic, giving, infrastructure, intelligence, maritime, market, military, news, positive_events, prediction, research, seismology, supply_chain, trade
buf.gen.yaml: Configures code generation plugins
buf.yaml: Proto linting rules and dependencies

`/src/generated`

WARNING: Never edit files here manually. This directory is regenerated by make generate.

client/: TypeScript RPC clients for frontend use
server/: TypeScript server stubs for backend handlers

Both are auto-generated from proto definitions.

`/server`

Server-side handler implementations that fulfill the generated service interfaces:

// Example: server/worldmonitor/seismology/v1/handler.ts
export const seismologyHandler: SeismologyService = {
  async listEarthquakes(req, context) {
    // Fetch from USGS API
    // Transform to proto response
    return { earthquakes };
  },
};

`/api`

Vercel serverless functions. Most routes are handled by the catch-all:

/api/[domain]/v1/[rpc].ts

This single file routes all RPC requests to their respective handlers.

`/scripts`

Build and utility scripts:

build-sidecar-sebuf.mjs: Bundles the sidecar gateway for Tauri
desktop-package.mjs: Creates signed installers for macOS/Windows
ais-relay.cjs: Railway relay server for AIS/OpenSky/Telegram
validate-rss-feeds.mjs: Tests all RSS feed URLs

`/e2e`

Playwright end-to-end tests:

runtime-fetch.spec.ts: Tests all API endpoints across variants
map-harness.spec.ts: Visual regression tests for map layers
circuit-breaker-persistence.spec.ts: Circuit breaker behavior
keyword-spike-flow.spec.ts: Keyword spike detection

Build Variants

World Monitor supports 4 build variants from a single codebase:

Variant	Domain	Focus	Data Layers
Full	worldmonitor.app	Geopolitics, military, conflicts	40+ layers
Tech	tech.worldmonitor.app	AI/ML, startups, cloud	Tech-specific
Finance	finance.worldmonitor.app	Markets, trading, central banks	Financial centers, exchanges
Happy	happy.worldmonitor.app	Good news, positive trends	Uplifting stories

Variants are controlled by the VITE_VARIANT environment variable.

Data Flow

News Aggregation

AI Summarization

Map Rendering Pipeline

Configuration Files

vite.config.ts

Configures:

Build variants with dynamic HTML meta injection
Brotli pre-compression
Service worker registration (PWA)
Dev server plugins (sebuf, RSS proxy, Polymarket, YouTube)
Chunk splitting strategy

playwright.config.ts

Configures:

Test directory: ./e2e
Base URL: http://127.0.0.1:4173
Browser: Chromium with SwiftShader (headless GPU)
Retries: 0 (fail fast)
Workers: 1 (serial execution)

tsconfig.json

TypeScript settings:

Target: ES2020
Module: ESNext
Strict mode enabled
Path alias: @/* → src/*

Makefile

Development commands:

make install — Install all dependencies
make generate — Generate code from protos
make lint — Lint proto files
make clean — Remove generated code

Next Steps

Proto API

Learn the proto-first workflow

Building

Build for production and desktop

Get Started

Core Features

Data & Intelligence

Variants

Configuration

Development

Deployment

​Tech Stack

​Frontend

​Backend (Serverless)

​Desktop (Tauri)

​AI & ML

​Data Processing

​Protobuf Tooling

​System Architecture

​High-Level Design

​Proto-First API Flow

​Desktop Architecture

​Project Structure

​Key Directories Explained

​/proto

​/src/generated

​/server

​/api

​/scripts

​/e2e

​Build Variants

​Data Flow

​News Aggregation

​AI Summarization

​Map Rendering Pipeline

​Configuration Files

​vite.config.ts

​playwright.config.ts

​tsconfig.json

​Makefile

​Next Steps