Proto-first API rebuild with sebuf code generation

[SebastienMelki]

Motivation

WorldMonitor currently has 56 hand-written API endpoint files in api/, each independently implementing fetch logic, error handling, CORS, request validation, and response typing. This means:

• 56 places where CORS headers can be wrong or missing
• 56 places where error handling is inconsistent
• 56 files with hand-written TypeScript interfaces that can drift from actual API responses
• Zero compile-time guarantees that request/response shapes match between client and server
• Zero auto-generated API documentation

Every new upstream data source requires writing a new endpoint file from scratch, copying boilerplate from an existing one, and hoping the types stay in sync.

What this PR introduces

This PR lays the foundation for a proto-first API rebuild — defining every API contract in Protocol Buffers and generating type-safe TypeScript clients, server handler interfaces, and OpenAPI documentation from a single source of truth.

The toolchain: sebuf v0.7.0

sebuf v0.7.0 was released with WorldMonitor as the primary design target. It includes:

• protoc-gen-ts-client — Generates typed client classes with injectable fetch, automatic JSON serialization, and proper error types (ValidationError, ApiError)
• protoc-gen-ts-server — Generates framework-agnostic server handler interfaces using the Web Fetch API. Works natively on Node 18+, Deno, Bun, Vercel Edge, and Cloudflare Workers — all environments WorldMonitor targets
• protoc-gen-openapiv3 — Generates OpenAPI v3 specs (YAML + JSON) from the same proto definitions
• Route descriptors — createXxxServiceRoutes() returns a RouteDescriptor[] that can be mounted on any HTTP framework, enabling a single catch-all Vercel function to replace all 56 individual files
• Proto-defined validation — Field constraints (required, min/max length, ranges, patterns) defined once in proto, enforced in both client and server
• Custom error hooks — onError callback for mapping domain exceptions to HTTP responses, no more per-file try/catch boilerplate

What's in this branch

79 proto files defining 17 domain services + shared core types:

Domain	Service	RPCs	Upstream Sources
seismology	SeismologyService	1	USGS
wildfire	WildfireService	1	NASA FIRMS
climate	ClimateService	1	Open-Meteo / ERA5
conflict	ConflictService	3	ACLED, UCDP, HAPI/HDX
displacement	DisplacementService	1	UNHCR
unrest	UnrestService	1	ACLED + GDELT
military	MilitaryService	3	OpenSky, Wingbits, AIS
aviation	AviationService	1	FAA, Eurocontrol
maritime	MaritimeService	2	AIS, NGA
cyber	CyberService	1	Feodo, URLhaus, OTX, AbuseIPDB, C2Intel
market	MarketService	4	Finnhub, Yahoo Finance, CoinGecko
prediction	PredictionService	1	Polymarket
economic	EconomicService	3	FRED, World Bank, EIA
news	NewsService	2	RSS feeds, Groq/OpenRouter
research	ResearchService	3	arXiv, GitHub, Hacker News
infrastructure	InfrastructureService	2	Cloudflare Radar, custom
intelligence	IntelligenceService	4	Computed (CII, PizzINT, GDELT, AI)

Core shared types (proto/worldmonitor/core/v1/):

• GeoCoordinates, BoundingBox — Validated WGS84 coordinates
• TimeRange — Unix epoch millisecond intervals
• PaginationRequest/PaginationResponse — Cursor-based pagination
• SeverityLevel, CriticalityLevel, TrendDirection — Cross-domain enums
• CountryCode — Validated ISO 3166-1 alpha-2
• 13 typed ID wrappers (EarthquakeID, CyberThreatID, etc.)
• GeneralError — Structured error types (RateLimited, UpstreamDown, GeoBlocked, MaintenanceMode)

Generated output (from make generate):

• 17 TypeScript client classes (src/generated/client/)
• 17 TypeScript server handler interfaces (src/generated/server/)
• 17 OpenAPI v3 specs in YAML + JSON (docs/api/)

Benefits

1. Single source of truth

Every field, type, enum, and constraint is defined once in a .proto file. Client types, server types, and API docs are all derived — they cannot drift.

2. Type-safe end-to-end

The generated SeismologyServiceHandler interface forces handler implementations to accept the correct request type and return the correct response type. No more as any or mismatched interfaces.

3. Automatic API documentation

Every service gets a complete OpenAPI v3 spec generated from the proto definitions — no manual Swagger/OpenAPI authoring needed. These live in docs/api/ and update automatically on make generate.

4. Validation at the boundary

Field constraints (required, min_len, max_len, pattern, gte, lte) are defined in proto and enforced by the generated server. Invalid requests get a structured 400 response with specific field violations — no hand-written validation code.

5. Unified server runtime

Instead of 56 individual Vercel edge functions, the plan is a single api/[[...path]].ts catch-all that mounts all RouteDescriptor[] arrays. CORS, error handling, and request validation happen once in shared middleware.

6. Framework-agnostic

The generated server code uses the Web Fetch API (Request/Response). It runs identically on Vercel Edge, Vite dev server, and Tauri desktop — no framework coupling.

7. Incremental migration

Old api/*.js files keep working. Vercel routing gives specific files priority over the catch-all. Each domain migrates independently: write the handler, mount it, verify, delete the old file.

8. Generated clients for frontend

Instead of hand-writing fetch('/api/earthquakes') with manual type assertions, the frontend will use:

const client = new SeismologyServiceClient('/api/seismology/v1');
const { earthquakes } = await client.listEarthquakes({ minMagnitude: 4.0 });
// earthquakes is fully typed as Earthquake[]

9. Built-in Tauri compatibility

Generated clients accept an injectable fetch function, defaulting to globalThis.fetch. The existing Tauri fetch patch intercepts all /api/* paths — new sebuf paths (/api/seismology/v1/list-earthquakes) work automatically with zero changes to src-tauri/.

What's NOT in this PR (yet)

• Server handlers — The handler implementations that actually call upstream APIs (Phase 2B)
• Catch-all gateway — The unified api/[[...path]].ts routing (Phase 2B)
• Frontend migration — Switching UI components to use generated clients (Phase 2C+)
• Legacy file deletion — Old api/*.js files remain until each domain is migrated and verified

How to review

This is a contracts-only PR — no runtime behavior changes. The app continues to work exactly as before.

Quick validation

make lint      # buf lint — should pass with zero errors
make generate  # regenerate all TypeScript + OpenAPI from protos
npx tsc --noEmit  # verify generated TypeScript compiles

What to look at

1. Proto conventions — Review a few domain protos (start with proto/worldmonitor/seismology/v1/ as the simplest). Check that field names, types, and comments make sense.
2. Entity shapes — Compare proto messages against src/types/index.ts to verify the proto definitions capture the same data. For example, compare the Earthquake message in seismology/v1/earthquake.proto with the Earthquake interface in src/types/index.ts.
3. Core types — Review proto/worldmonitor/core/v1/ for the shared building blocks (geo, pagination, time, severity, identifiers).
4. Generated output — Spot-check a generated client (src/generated/client/worldmonitor/seismology/v1/service_client.ts) and server (src/generated/server/worldmonitor/military/v1/service_server.ts) to see the quality of generated TypeScript.
5. OpenAPI specs — Open any docs/api/*.openapi.yaml to see the auto-generated API documentation.

What NOT to review in detail

• Individual generated TypeScript files — these are machine output, they'll regenerate on any proto change
• The .planning/ directory — internal planning docs, not shipped code

Architecture diagram

proto/worldmonitor/{domain}/v1/          ← You define contracts here
        │
        ├── make generate
        │
        ├─→ src/generated/client/{domain}/v1/service_client.ts   (frontend uses this)
        ├─→ src/generated/server/{domain}/v1/service_server.ts   (handler implements this)
        └─→ docs/api/{Domain}Service.openapi.yaml                (docs get this free)
                                                                  
api/server/worldmonitor/{domain}/v1/handler.ts  ← You write handlers here (Phase 2B)
        │
        └─→ api/[[...path]].ts  ← Single catch-all mounts all routes (Phase 2B)

---

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ready	Preview, Comment	Feb 18, 2026 4:42pm
worldmonitor-finance	Ready	Preview, Comment	Feb 18, 2026 4:42pm
worldmonitor-startup	Ready	Preview, Comment	Feb 18, 2026 4:42pm

[koala73]

Massive work 😃 ! @SebastienMelki