> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascendgtm.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the V5 Gateway works under the hood.

# 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` — ADR-driven decision history

## 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. **Two-plane architecture** — Gateway Worker (execution) + Context Worker (signals/facts). Service Bindings only.

## Cron schedules

| Schedule       | Job             | Description                           |
| -------------- | --------------- | ------------------------------------- |
| `*/5 * * * *`  | System health   | Writes health snapshot to KV          |
| `*/15 * * * *` | Token health    | Checks for expiring/expired tokens    |
| `*/30 * * * *` | Provider health | Canary checks against registered APIs |
| `0 4 * * *`    | Error cleanup   | Prunes old error\_ledger entries      |
| `0 6 * * *`    | Autoresearch    | Daily briefing with suggestions       |