# blockrunai/clawrouter architecture

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

- Interactive diagram: https://gitdiagram.com/blockrunai/clawrouter
- Repository: https://github.com/blockrunai/clawrouter

## Overview

ClawRouter is a local LLM routing gateway and agent-facing plugin: an agent or application submits model/tool requests, local routing selects a capable model, and the proxy reaches BlockRun/provider services with API-key or wallet/x402 billing. The repository also provides model compression, wallet management, partner tools, Polymarket operations, and a desktop dashboard for proxy, agent, and wallet management. The main entrypoint, desktop manager, compression, and Polymarket client excerpts support the links shown; broader feature links are limited to README capabilities and explicit exported/runtime paths.

Main entry points: [`src/index.ts`](https://github.com/blockrunai/clawrouter/blob/main/src/index.ts) (Plugin entry), [`src/proxy.ts`](https://github.com/blockrunai/clawrouter/blob/main/src/proxy.ts) (Local proxy), [`apps/desktop/electron/core/manager.ts`](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/core/manager.ts) (Runtime manager), [`src/auth.ts`](https://github.com/blockrunai/clawrouter/blob/main/src/auth.ts) (Wallet and auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Request Routing"]
  node_plugin["Plugin entry<br/>[index.ts]"]
  node_router["Model router<br/>[index.ts]"]
  node_proxy["Local proxy<br/>[proxy.ts]"]
  node_provider["Provider gateway<br/>[provider.ts]"]
  node_compression["Context compression<br/>[index.ts]"]
  node_models["Model catalog<br/>[models.ts]"]
  node_response["Response cache<br/>[response-cache.ts]"]
  node_usage["Usage statistics<br/>[stats.ts]"]
end

subgraph group_payments["Identity and Billing"]
  node_auth["Wallet and auth<br/>[auth.ts]"]
  node_wallet["Wallet derivation<br/>[wallet.ts]"]
  node_session["Session billing<br/>[session.ts]"]
  node_balance["Balance checks<br/>[balance.ts]"]
  node_payment["Payment preauthorization<br/>[payment-preauth.ts]"]
  node_state[("Local state<br/>[response-store.ts]")]
end

subgraph group_tools["Agent Capabilities"]
  node_polymarket["Market operations<br/>[tool.ts]"]
  node_polyclient["Market client<br/>[client.ts]"]
  node_partners["Partner tools<br/>[tools.ts]"]
  node_search["Web search"]
end

subgraph group_desktop["Desktop Management"]
  node_desktopui["Desktop dashboard<br/>[App.tsx]"]
  node_desktopapi["Desktop API<br/>[api.ts]"]
  node_electron["Electron IPC<br/>[main.ts]"]
  node_manager["Runtime manager<br/>[manager.ts]"]
  node_supervisor["Service supervisor<br/>[supervisor.ts]"]
end

node_agent(("Agent / SDK"))
node_blockrun{{"BlockRun gateway"}}
node_providers{{"Model providers"}}
node_chains{{"Blockchain networks"}}
node_polymarketservice{{"Polymarket CLOB"}}

node_agent -->|"submits requests"| node_plugin
node_plugin -->|"forwards requests"| node_proxy
node_plugin -->|"selects models"| node_router
node_router -->|"resolves aliases"| node_models
node_proxy -->|"compresses context"| node_compression
node_proxy -->|"dispatches inference"| node_provider
node_provider -->|"sends API calls"| node_blockrun
node_provider -->|"sends inference"| node_providers
node_proxy -->|"checks cache"| node_response
node_proxy -->|"records usage"| node_usage
node_plugin -->|"resolves credentials"| node_auth
node_auth -->|"derives keys"| node_wallet
node_plugin -->|"manages billing session"| node_session
node_session -->|"checks funds"| node_balance
node_session -->|"preauthorizes payment"| node_payment
node_payment -->|"settles x402"| node_chains
node_auth -->|"persists wallet state"| node_state
node_plugin -->|"exposes market tools"| node_polymarket
node_polymarket -->|"places market operations"| node_polyclient
node_polyclient -->|"authenticates and trades"| node_polymarketservice
node_plugin -->|"registers partner tools"| node_partners
node_plugin -->|"provides search"| node_search
node_desktopui -->|"invokes dashboard actions"| node_desktopapi
node_desktopapi -->|"sends IPC"| node_electron
node_electron -->|"dispatches operations"| node_manager
node_manager -->|"controls proxy service"| node_supervisor
node_supervisor -->|"starts and monitors"| node_proxy
node_manager -->|"reads wallet state"| node_auth
node_manager -->|"requests balances and onramp"| node_blockrun

click node_plugin "https://github.com/blockrunai/clawrouter/blob/main/src/index.ts"
click node_router "https://github.com/blockrunai/clawrouter/blob/main/src/router/index.ts"
click node_proxy "https://github.com/blockrunai/clawrouter/blob/main/src/proxy.ts"
click node_provider "https://github.com/blockrunai/clawrouter/blob/main/src/provider.ts"
click node_compression "https://github.com/blockrunai/clawrouter/blob/main/src/compression/index.ts"
click node_models "https://github.com/blockrunai/clawrouter/blob/main/src/models.ts"
click node_response "https://github.com/blockrunai/clawrouter/blob/main/src/response-cache.ts"
click node_usage "https://github.com/blockrunai/clawrouter/blob/main/src/stats.ts"
click node_auth "https://github.com/blockrunai/clawrouter/blob/main/src/auth.ts"
click node_wallet "https://github.com/blockrunai/clawrouter/blob/main/src/wallet.ts"
click node_session "https://github.com/blockrunai/clawrouter/blob/main/src/session.ts"
click node_balance "https://github.com/blockrunai/clawrouter/blob/main/src/balance.ts"
click node_payment "https://github.com/blockrunai/clawrouter/blob/main/src/payment-preauth.ts"
click node_polymarket "https://github.com/blockrunai/clawrouter/blob/main/src/polymarket/tool.ts"
click node_polyclient "https://github.com/blockrunai/clawrouter/blob/main/src/polymarket/client.ts"
click node_partners "https://github.com/blockrunai/clawrouter/blob/main/src/partners/tools.ts"
click node_search "https://github.com/blockrunai/clawrouter/blob/main/src/web-search-provider.ts"
click node_desktopui "https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/src/App.tsx"
click node_desktopapi "https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/src/api.ts"
click node_electron "https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/main.ts"
click node_manager "https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/core/manager.ts"
click node_supervisor "https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/core/supervisor.ts"
click node_state "https://github.com/blockrunai/clawrouter/blob/main/src/response-store.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_plugin,node_router,node_proxy,node_provider,node_compression,node_models,node_response,node_usage toneBlue
class node_auth,node_wallet,node_session,node_balance,node_payment,node_state toneAmber
class node_polymarket,node_polyclient,node_partners,node_search toneMint
class node_desktopui,node_desktopapi,node_electron,node_manager,node_supervisor toneRose
class node_agent,node_blockrun,node_providers,node_chains,node_polymarketservice toneIndigo
```

## Components

### Request Routing

- [Plugin entry](https://github.com/blockrunai/clawrouter/blob/main/src/index.ts): `src/index.ts`
- [Model router](https://github.com/blockrunai/clawrouter/blob/main/src/router/index.ts): `src/router/index.ts`
- [Local proxy](https://github.com/blockrunai/clawrouter/blob/main/src/proxy.ts): `src/proxy.ts`
- [Provider gateway](https://github.com/blockrunai/clawrouter/blob/main/src/provider.ts): `src/provider.ts`
- [Context compression](https://github.com/blockrunai/clawrouter/blob/main/src/compression/index.ts): `src/compression/index.ts`
- [Model catalog](https://github.com/blockrunai/clawrouter/blob/main/src/models.ts): `src/models.ts`
- [Response cache](https://github.com/blockrunai/clawrouter/blob/main/src/response-cache.ts): `src/response-cache.ts`
- [Usage statistics](https://github.com/blockrunai/clawrouter/blob/main/src/stats.ts): `src/stats.ts`

### Identity and Billing

- [Wallet and auth](https://github.com/blockrunai/clawrouter/blob/main/src/auth.ts): `src/auth.ts`
- [Wallet derivation](https://github.com/blockrunai/clawrouter/blob/main/src/wallet.ts): `src/wallet.ts`
- [Session billing](https://github.com/blockrunai/clawrouter/blob/main/src/session.ts): `src/session.ts`
- [Balance checks](https://github.com/blockrunai/clawrouter/blob/main/src/balance.ts): `src/balance.ts`
- [Payment preauthorization](https://github.com/blockrunai/clawrouter/blob/main/src/payment-preauth.ts): `src/payment-preauth.ts`
- [Local state](https://github.com/blockrunai/clawrouter/blob/main/src/response-store.ts): `src/response-store.ts`

### Agent Capabilities

- [Market operations](https://github.com/blockrunai/clawrouter/blob/main/src/polymarket/tool.ts): `src/polymarket/tool.ts`
- [Market client](https://github.com/blockrunai/clawrouter/blob/main/src/polymarket/client.ts): `src/polymarket/client.ts`
- [Partner tools](https://github.com/blockrunai/clawrouter/blob/main/src/partners/tools.ts): `src/partners/tools.ts`
- [Web search](https://github.com/blockrunai/clawrouter/blob/main/src/web-search-provider.ts): `src/web-search-provider.ts`

### Desktop Management

- [Desktop dashboard](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Desktop API](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/src/api.ts): `apps/desktop/src/api.ts`
- [Electron IPC](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/main.ts): `apps/desktop/electron/main.ts`
- [Runtime manager](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/core/manager.ts): `apps/desktop/electron/core/manager.ts`
- [Service supervisor](https://github.com/blockrunai/clawrouter/blob/main/apps/desktop/electron/core/supervisor.ts): `apps/desktop/electron/core/supervisor.ts`

### Other components

- **Agent / SDK**
- **BlockRun gateway**
- **Model providers**
- **Blockchain networks**
- **Polymarket CLOB**

## Connections

- Agent / SDK → Plugin entry: submits requests
- Plugin entry → Local proxy: forwards requests
- Plugin entry → Model router: selects models
- Model router → Model catalog: resolves aliases
- Local proxy → Context compression: compresses context
- Local proxy → Provider gateway: dispatches inference
- Provider gateway → BlockRun gateway: sends API calls
- Provider gateway → Model providers: sends inference
- Local proxy → Response cache: checks cache
- Local proxy → Usage statistics: records usage
- Plugin entry → Wallet and auth: resolves credentials
- Wallet and auth → Wallet derivation: derives keys
- Plugin entry → Session billing: manages billing session
- Session billing → Balance checks: checks funds
- Session billing → Payment preauthorization: preauthorizes payment
- Payment preauthorization → Blockchain networks: settles x402
- Wallet and auth → Local state: persists wallet state
- Plugin entry → Market operations: exposes market tools
- Market operations → Market client: places market operations
- Market client → Polymarket CLOB: authenticates and trades
- Plugin entry → Partner tools: registers partner tools
- Plugin entry → Web search: provides search
- Desktop dashboard → Desktop API: invokes dashboard actions
- Desktop API → Electron IPC: sends IPC
- Electron IPC → Runtime manager: dispatches operations
- Runtime manager → Service supervisor: controls proxy service
- Service supervisor → Local proxy: starts and monitors
- Runtime manager → Wallet and auth: reads wallet state
- Runtime manager → BlockRun gateway: requests balances and onramp