Skip to main content

Architecture

How the V5 Gateway works under the hood.

Overview​

AI Agent / App
     │
     ▼
┌─────────────────────────────────┐
│   Cloudflare Worker (Hono.js)   │
│                                 │
│  Auth → Token → Route → Execute │
│   5ms    2ms    3ms     ≤30s    │
└──────────┬──────────────────────┘
           │
     ┌─────┼─────┐
     ▼     ▼     ▼
    KV    DO     D1
  (hot)  (OAuth) (cold)

Request flow (≤10ms gateway overhead)​

  1. Auth (~5ms) — Hash bearer token, look up tenant_auth:{hash} in KV
  2. Token (~2ms) — Read tokens:{tenant}:{provider}:{account_id} from KV
  3. Route (~3ms) — Read api_config:{provider} from KV, build URL + headers
  4. Execute (≤30s) — Proxy request to upstream API with AbortController timeout
  5. Return — Structured JSON response with success/error status

Data stores​

KV (hot path — sub-ms reads)​

  • tenant_auth:{hash} — bearer token → tenant mapping
  • tokens:{tenant}:{provider}:{account_id} — cached OAuth/API tokens
  • api_config:{provider} — base URLs, versions, auth types, endpoints
  • tenant_config:{tenant} — tenant metadata, connected providers, billing

Durable Objects (background only)​

  • TokenManager — one DO per {tenant}:{provider}:{account_id} triplet
  • Alarm fires 10 minutes before token expiry
  • Refreshes via provider's token endpoint
  • Writes new token to KV
  • Request path NEVER contacts a DO

D1 (cold path only)​

  • error_ledger — failed request log for debugging
  • kv_audit — every admin KV write (key, action, old/new hashes, source, timestamp)
  • decision_log — self-improvement substrate (Phase 0)

Design principles​

  1. Fail-fast — No retries in the gateway. Caller handles retries.
  2. KV-only hot path — No D1 reads during request processing.
  3. Proactive token refresh — DOs refresh before expiry, not on-demand.
  4. Multi-tenant isolation — Every KV key is tenant-scoped.
  5. One Worker — No Service Bindings, no multi-Worker complexity.

Cron schedules​

ScheduleJobDescription
*/5 * * * *System healthWrites health snapshot to KV
*/15 * * * *Token healthChecks for expiring/expired tokens
*/30 * * * *Provider healthCanary checks against registered APIs
0 4 * * *Error cleanupPrunes old error_ledger entries
0 6 * * *AutoresearchDaily briefing with suggestions