Architecture
Control plane vs data plane, Workers, Postgres, and agent surfaces.
View as Markdown →Ozma splits control plane (discovery, auth, billing, provider ops) from data plane (proxied API calls). Both run on Cloudflare Workers; state lives in Neon Postgres with Drizzle ORM.
Planes
| Component | URL | Role |
|---|---|---|
| API worker | https://api.ozma.app |
Catalog, keys, billing webhooks, provider CRUD, merit crons |
| Gateway worker | https://gateway.ozma.app |
Auth, spend counters, credential injection, proxy, usage enqueue |
| MCP worker | https://mcp.ozma.app |
MCP tools + OAuth 2.1 |
| Web | https://ozma.app |
Next.js marketplace, dashboard, docs |
Gateway hot path
ALL /v1/proxy/:apiSlug/*:
- Validate API key (
proxy:call) - Resolve live endpoint + price
- Check required provider terms (428 if missing)
- SpendCounter DO — budget / daily / per-call
- Decrypt upstream credentials (AES-GCM); inject into outbound request
- Forward to provider
base_url - On success — record
usage_events, update key spend, queue metering - On failure — refund reservation
Stripe meter emission and Connect payouts run asynchronously via queues and scheduled crons on the API worker.
Agent surfaces
REST is the source of truth. @ozma_app/sdk, @ozma_app/cli, and MCP wrap the same endpoints. The web app uses static export with client-side polling for live panels (market ticker, dashboard).
Shared packages: @ozma_app/core (envelope, crypto), @ozma/db, @ozma/merit, @ozma_app/sdk.
Merit & health
Cron jobs roll up provider stats, refresh leaderboards, compute OzmaScores, probe live API health, and finalize scheduled price changes. Suspended APIs are excluded from public catalog merit.