# samucamg/veroroute-edge architecture

> Architecture diagram of the GitHub repository samucamg/veroroute-edge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samucamg/veroroute-edge
- Repository: https://github.com/samucamg/veroroute-edge

## Overview

VeroRoute Edge is a Cloudflare Workers AI gateway. Clients authenticate and submit OpenAI- or Anthropic-shaped requests; the gateway normalizes and enriches requests, then routes them across configured providers with fallback and resilience controls. It also exposes web search/fetch and MCP tools, plus an authenticated dashboard for provider, key, and route administration. The graph reflects documented capabilities where implementation excerpts are incomplete; unsampled subsystem links are omitted when their caller is unclear.

Main entry points: [`src/routing/cascade.ts`](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/cascade.ts) (Cascade Dispatch), [`src/index.ts`](https://github.com/samucamg/veroroute-edge/blob/master/src/index.ts) (HTTP Gateway), [`src/oauth/antigravity.ts`](https://github.com/samucamg/veroroute-edge/blob/master/src/oauth/antigravity.ts) (OAuth Tokens), [`src/admin/routes.ts`](https://github.com/samucamg/veroroute-edge/blob/master/src/admin/routes.ts) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway API"]
  node_worker["HTTP Gateway<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_anthropic["API Translation<br/>[anthropic.ts]"]
  node_compression["Request Preparation<br/>[pipeline.ts]"]
  node_modality["Modality Bridge<br/>[bridge.ts]"]
end

subgraph group_routing["Routing Core"]
  node_cascade["Cascade Dispatch<br/>[cascade.ts]"]
  node_registry["Model Registry<br/>[modelRegistry.ts]"]
  node_providerconfig["Provider Config<br/>[providers.ts]"]
  node_keypool["Credential Pool<br/>[keyPool.ts]"]
  node_ratelimit["Rate Limiting<br/>[rateLimiter.ts]"]
  node_circuit["Circuit Breakers<br/>[circuitBreaker.ts]"]
  node_resilience["Retry And Resilience<br/>[resilience.ts]"]
  node_cache["Response Cache<br/>[responseCache.ts]"]
  node_cost["Cost Tracking<br/>[costTracker.ts]"]
end

subgraph group_integrations["AI And Search"]
  node_providers["Provider Adapters"]
  node_cloudflareai["Workers AI Adapter<br/>[cloudflare-ai.ts]"]
  node_antigravity["Antigravity Adapter<br/>[antigravity.ts]"]
  node_oauth["OAuth Tokens<br/>[antigravity.ts]"]
end

subgraph group_management["Admin And Config"]
  node_adminui["Admin Dashboard<br/>[dashboard.ts]"]
  node_adminroutes["Admin API<br/>[routes.ts]"]
  node_adminstore[("Admin Config Store<br/>[store.ts]")]
end

subgraph group_tools["Search And MCP"]
  node_searchapi["Search API<br/>[dispatcher.ts]"]
  node_searchengines["Search Engines<br/>[searxng.ts]"]
  node_webfetch["Web Fetch<br/>[jina.ts]"]
  node_mcp["MCP Server<br/>[server.ts]"]
end

node_client(("API Client"))
node_upstreams(("AI Providers"))
node_searchservices(("Search Services"))
node_kv[("Cloudflare KV")]

node_client -->|"sends requests"| node_worker
node_worker -->|"checks identity"| node_auth
node_worker -->|"translates messages"| node_anthropic
node_worker -->|"bridges modalities"| node_modality
node_worker -->|"augments with search"| node_searchapi
node_worker -->|"prepares request"| node_compression
node_worker -->|"dispatches completion"| node_cascade
node_worker -->|"fetches pages"| node_webfetch
node_worker -->|"mounts admin API"| node_adminroutes
node_cascade -->|"resolves models"| node_registry
node_cascade -->|"loads provider config"| node_providerconfig
node_cascade -->|"selects credentials"| node_keypool
node_cascade -->|"enforces limits"| node_ratelimit
node_cascade -->|"checks failures"| node_circuit
node_cascade -->|"handles retries"| node_resilience
node_cascade -.->|"checks responses"| node_cache
node_cascade -.->|"tracks usage"| node_cost
node_cascade -->|"dispatches requests"| node_providers
node_cascade -->|"dispatches requests"| node_cloudflareai
node_cascade -->|"dispatches requests"| node_antigravity
node_antigravity -->|"obtains access token"| node_oauth
node_providers -->|"calls models"| node_upstreams
node_cloudflareai -->|"calls models"| node_upstreams
node_antigravity -->|"calls models"| node_upstreams
node_auth -->|"reads auth config"| node_adminstore
node_adminui -->|"calls endpoints"| node_adminroutes
node_adminroutes -->|"reads and updates"| node_adminstore
node_adminroutes -->|"tests provider"| node_cloudflareai
node_oauth -->|"reads OAuth credentials"| node_adminstore
node_oauth -->|"selects refresh credential"| node_keypool
node_oauth -->|"caches access token"| node_kv
node_keypool -.->|"reads credentials"| node_kv
node_ratelimit -.->|"tracks request windows"| node_kv
node_circuit -.->|"persists cooldowns"| node_kv
node_searchapi -->|"dispatches queries"| node_searchengines
node_searchengines -->|"queries providers"| node_searchservices
node_webfetch -->|"retrieves page content"| node_searchservices
node_mcp -->|"runs web search"| node_searchapi
node_mcp -->|"fetches page"| node_webfetch
node_mcp -->|"lists providers"| node_registry

click node_worker "https://github.com/samucamg/veroroute-edge/blob/master/src/index.ts"
click node_auth "https://github.com/samucamg/veroroute-edge/blob/master/src/admin/auth.ts"
click node_anthropic "https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/anthropic.ts"
click node_compression "https://github.com/samucamg/veroroute-edge/blob/master/src/compression/pipeline.ts"
click node_modality "https://github.com/samucamg/veroroute-edge/blob/master/src/modality/bridge.ts"
click node_cascade "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/cascade.ts"
click node_registry "https://github.com/samucamg/veroroute-edge/blob/master/src/config/modelRegistry.ts"
click node_providerconfig "https://github.com/samucamg/veroroute-edge/blob/master/src/config/providers.ts"
click node_keypool "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/keyPool.ts"
click node_ratelimit "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/rateLimiter.ts"
click node_circuit "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/circuitBreaker.ts"
click node_resilience "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/resilience.ts"
click node_cache "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/responseCache.ts"
click node_cost "https://github.com/samucamg/veroroute-edge/blob/master/src/routing/costTracker.ts"
click node_providers "https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/openai-compatible.ts"
click node_cloudflareai "https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/cloudflare-ai.ts"
click node_antigravity "https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/antigravity.ts"
click node_oauth "https://github.com/samucamg/veroroute-edge/blob/master/src/oauth/antigravity.ts"
click node_adminui "https://github.com/samucamg/veroroute-edge/blob/master/src/ui/dashboard.ts"
click node_adminroutes "https://github.com/samucamg/veroroute-edge/blob/master/src/admin/routes.ts"
click node_adminstore "https://github.com/samucamg/veroroute-edge/blob/master/src/admin/store.ts"
click node_searchapi "https://github.com/samucamg/veroroute-edge/blob/master/src/search/dispatcher.ts"
click node_searchengines "https://github.com/samucamg/veroroute-edge/blob/master/src/search/searxng.ts"
click node_webfetch "https://github.com/samucamg/veroroute-edge/blob/master/src/search/jina.ts"
click node_mcp "https://github.com/samucamg/veroroute-edge/blob/master/src/mcp/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_worker,node_auth,node_anthropic,node_compression,node_modality,node_client toneBlue
class node_cascade,node_registry,node_providerconfig,node_keypool,node_ratelimit,node_circuit,node_resilience,node_cache,node_cost,node_kv toneAmber
class node_providers,node_cloudflareai,node_antigravity,node_oauth toneMint
class node_adminui,node_adminroutes,node_adminstore toneRose
class node_searchapi,node_searchengines,node_webfetch,node_mcp,node_upstreams,node_searchservices toneIndigo
```

## Components

### Gateway API

- [HTTP Gateway](https://github.com/samucamg/veroroute-edge/blob/master/src/index.ts): `src/index.ts`
- [Authentication](https://github.com/samucamg/veroroute-edge/blob/master/src/admin/auth.ts): `src/admin/auth.ts`
- [API Translation](https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/anthropic.ts): `src/adapters/anthropic.ts`
- [Request Preparation](https://github.com/samucamg/veroroute-edge/blob/master/src/compression/pipeline.ts): `src/compression/pipeline.ts`
- [Modality Bridge](https://github.com/samucamg/veroroute-edge/blob/master/src/modality/bridge.ts): `src/modality/bridge.ts`

### Routing Core

- [Cascade Dispatch](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/cascade.ts): `src/routing/cascade.ts`
- [Model Registry](https://github.com/samucamg/veroroute-edge/blob/master/src/config/modelRegistry.ts): `src/config/modelRegistry.ts`
- [Provider Config](https://github.com/samucamg/veroroute-edge/blob/master/src/config/providers.ts): `src/config/providers.ts`
- [Credential Pool](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/keyPool.ts): `src/routing/keyPool.ts`
- [Rate Limiting](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/rateLimiter.ts): `src/routing/rateLimiter.ts`
- [Circuit Breakers](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/circuitBreaker.ts): `src/routing/circuitBreaker.ts`
- [Retry And Resilience](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/resilience.ts): `src/routing/resilience.ts`
- [Response Cache](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/responseCache.ts): `src/routing/responseCache.ts`
- [Cost Tracking](https://github.com/samucamg/veroroute-edge/blob/master/src/routing/costTracker.ts): `src/routing/costTracker.ts`

### AI And Search

- [Provider Adapters](https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/openai-compatible.ts): `src/adapters/openai-compatible.ts`
- [Workers AI Adapter](https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/cloudflare-ai.ts): `src/adapters/cloudflare-ai.ts`
- [Antigravity Adapter](https://github.com/samucamg/veroroute-edge/blob/master/src/adapters/antigravity.ts): `src/adapters/antigravity.ts`
- [OAuth Tokens](https://github.com/samucamg/veroroute-edge/blob/master/src/oauth/antigravity.ts): `src/oauth/antigravity.ts`

### Admin And Config

- [Admin Dashboard](https://github.com/samucamg/veroroute-edge/blob/master/src/ui/dashboard.ts): `src/ui/dashboard.ts`
- [Admin API](https://github.com/samucamg/veroroute-edge/blob/master/src/admin/routes.ts): `src/admin/routes.ts`
- [Admin Config Store](https://github.com/samucamg/veroroute-edge/blob/master/src/admin/store.ts): `src/admin/store.ts`

### Search And MCP

- [Search API](https://github.com/samucamg/veroroute-edge/blob/master/src/search/dispatcher.ts): `src/search/dispatcher.ts`
- [Search Engines](https://github.com/samucamg/veroroute-edge/blob/master/src/search/searxng.ts): `src/search/searxng.ts`
- [Web Fetch](https://github.com/samucamg/veroroute-edge/blob/master/src/search/jina.ts): `src/search/jina.ts`
- [MCP Server](https://github.com/samucamg/veroroute-edge/blob/master/src/mcp/server.ts): `src/mcp/server.ts`

### Other components

- **API Client**
- **AI Providers**
- **Search Services**
- **Cloudflare KV**

## Connections

- API Client → HTTP Gateway: sends requests
- HTTP Gateway → Authentication: checks identity
- HTTP Gateway → API Translation: translates messages
- HTTP Gateway → Modality Bridge: bridges modalities
- HTTP Gateway → Search API: augments with search
- HTTP Gateway → Request Preparation: prepares request
- HTTP Gateway → Cascade Dispatch: dispatches completion
- HTTP Gateway → Web Fetch: fetches pages
- HTTP Gateway → Admin API: mounts admin API
- Cascade Dispatch → Model Registry: resolves models
- Cascade Dispatch → Provider Config: loads provider config
- Cascade Dispatch → Credential Pool: selects credentials
- Cascade Dispatch → Rate Limiting: enforces limits
- Cascade Dispatch → Circuit Breakers: checks failures
- Cascade Dispatch → Retry And Resilience: handles retries
- Cascade Dispatch → Response Cache: checks responses
- Cascade Dispatch → Cost Tracking: tracks usage
- Cascade Dispatch → Provider Adapters: dispatches requests
- Cascade Dispatch → Workers AI Adapter: dispatches requests
- Cascade Dispatch → Antigravity Adapter: dispatches requests
- Antigravity Adapter → OAuth Tokens: obtains access token
- Provider Adapters → AI Providers: calls models
- Workers AI Adapter → AI Providers: calls models
- Antigravity Adapter → AI Providers: calls models
- Authentication → Admin Config Store: reads auth config
- Admin Dashboard → Admin API: calls endpoints
- Admin API → Admin Config Store: reads and updates
- Admin API → Workers AI Adapter: tests provider
- OAuth Tokens → Admin Config Store: reads OAuth credentials
- OAuth Tokens → Credential Pool: selects refresh credential
- OAuth Tokens → Cloudflare KV: caches access token
- Credential Pool → Cloudflare KV: reads credentials
- Rate Limiting → Cloudflare KV: tracks request windows
- Circuit Breakers → Cloudflare KV: persists cooldowns
- Search API → Search Engines: dispatches queries
- Search Engines → Search Services: queries providers
- Web Fetch → Search Services: retrieves page content
- MCP Server → Search API: runs web search
- MCP Server → Web Fetch: fetches page
- MCP Server → Model Registry: lists providers