# workweave/router architecture

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

- Interactive diagram: https://gitdiagram.com/workweave/router
- Repository: https://github.com/workweave/router

## Overview

Weave Router is a model-routing gateway with an admin dashboard and policy-serving control plane. The principal flow is a client request entering the HTTP server, passing through proxy handling and routing, then reaching a provider; usage and routing outcomes support analytics. The tree indicates additional policy, subscription, billing, and HMM capabilities. Source excerpts confirm server route registration and the composition-root role, but most runtime links are not shown, so those are marked unverified rather than asserted.

Main entry points: [`internal/proxy/service.go`](https://github.com/workweave/router/blob/main/internal/proxy/service.go) (Request proxy), [`internal/server/server.go`](https://github.com/workweave/router/blob/main/internal/server/server.go) (HTTP server), [`internal/router/router.go`](https://github.com/workweave/router/blob/main/internal/router/router.go) (Model router), [`internal/dispatch/executor.go`](https://github.com/workweave/router/blob/main/internal/dispatch/executor.go) (Provider dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and routing"]
  node_http["HTTP server<br/>[server.go]"]
  node_proxy["Request proxy<br/>[service.go]"]
  node_router["Model router<br/>[router.go]"]
  node_dispatch["Provider dispatch<br/>[executor.go]"]
  node_providers["Provider clients"]
  node_auth["Identity and auth<br/>[service.go]"]
end

subgraph group_policy["Policy and control plane"]
  node_policyclient["Policy client<br/>[client.go]"]
  node_policyregistry["Policy registry"]
  node_hmm["HMM routing"]
end

subgraph group_operations["Accounts and analytics"]
  node_subscriptions["Provider subscriptions<br/>[manager.go]"]
  node_billing["Billing<br/>[service.go]"]
  node_analytics["Routing analytics<br/>[service.go]"]
  node_postgres[("Postgres repositories<br/>[repository.go]")]
end

subgraph group_interface["Admin interface"]
  node_frontend["Admin dashboard<br/>[page.tsx]"]
  node_adminapi["Admin API"]
end

node_client(("API client"))

node_client -.->|"sends requests"| node_http
node_http -.->|"routes requests"| node_proxy
node_proxy -.->|"requests decisions"| node_router
node_proxy -.->|"dispatches inference"| node_dispatch
node_dispatch -.->|"calls providers"| node_providers
node_proxy -.->|"uses identity"| node_auth
node_router -.->|"consults policy"| node_policyclient
node_policyclient -.->|"fetches serving data"| node_policyregistry
node_router -.->|"uses HMM routing"| node_hmm
node_proxy -.->|"leases accounts"| node_subscriptions
node_proxy -.->|"checks or records spend"| node_billing
node_proxy -.->|"emits outcomes"| node_analytics
node_analytics -.->|"persists analytics"| node_postgres
node_billing -.->|"persists billing data"| node_postgres
node_frontend -.->|"calls admin routes"| node_adminapi
node_http -->|"registers admin routes"| node_adminapi
node_http -->|"registers metrics handlers"| node_proxy
node_router -.->|"wired at startup"| node_providers

click node_http "https://github.com/workweave/router/blob/main/internal/server/server.go"
click node_proxy "https://github.com/workweave/router/blob/main/internal/proxy/service.go"
click node_router "https://github.com/workweave/router/blob/main/internal/router/router.go"
click node_dispatch "https://github.com/workweave/router/blob/main/internal/dispatch/executor.go"
click node_providers "https://github.com/workweave/router/tree/main/internal/providers"
click node_auth "https://github.com/workweave/router/blob/main/internal/auth/service.go"
click node_policyclient "https://github.com/workweave/router/blob/main/internal/policyclient/client.go"
click node_policyregistry "https://github.com/workweave/router/blob/main/internal/policyregistry/serving_controller.go"
click node_hmm "https://github.com/workweave/router/tree/main/internal/router/hmm"
click node_subscriptions "https://github.com/workweave/router/blob/main/internal/subscriptions/manager.go"
click node_billing "https://github.com/workweave/router/blob/main/internal/billing/service.go"
click node_analytics "https://github.com/workweave/router/blob/main/internal/analytics/service.go"
click node_postgres "https://github.com/workweave/router/blob/main/internal/postgres/repository.go"
click node_frontend "https://github.com/workweave/router/blob/main/frontend/src/app/(app)/dashboard/page.tsx"
click node_adminapi "https://github.com/workweave/router/tree/main/internal/api/admin"

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_http,node_proxy,node_router,node_dispatch,node_providers,node_auth,node_client toneBlue
class node_policyclient,node_policyregistry,node_hmm toneAmber
class node_subscriptions,node_billing,node_analytics,node_postgres toneMint
class node_frontend,node_adminapi toneRose
```

## Components

### Gateway and routing

- [HTTP server](https://github.com/workweave/router/blob/main/internal/server/server.go): `internal/server/server.go`
- [Request proxy](https://github.com/workweave/router/blob/main/internal/proxy/service.go): `internal/proxy/service.go`
- [Model router](https://github.com/workweave/router/blob/main/internal/router/router.go): `internal/router/router.go`
- [Provider dispatch](https://github.com/workweave/router/blob/main/internal/dispatch/executor.go): `internal/dispatch/executor.go`
- [Provider clients](https://github.com/workweave/router/tree/main/internal/providers): `internal/providers`
- [Identity and auth](https://github.com/workweave/router/blob/main/internal/auth/service.go): `internal/auth/service.go`

### Policy and control plane

- [Policy client](https://github.com/workweave/router/blob/main/internal/policyclient/client.go): `internal/policyclient/client.go`
- [Policy registry](https://github.com/workweave/router/blob/main/internal/policyregistry/serving_controller.go): `internal/policyregistry/serving_controller.go`
- [HMM routing](https://github.com/workweave/router/tree/main/internal/router/hmm): `internal/router/hmm`

### Accounts and analytics

- [Provider subscriptions](https://github.com/workweave/router/blob/main/internal/subscriptions/manager.go): `internal/subscriptions/manager.go`
- [Billing](https://github.com/workweave/router/blob/main/internal/billing/service.go): `internal/billing/service.go`
- [Routing analytics](https://github.com/workweave/router/blob/main/internal/analytics/service.go): `internal/analytics/service.go`
- [Postgres repositories](https://github.com/workweave/router/blob/main/internal/postgres/repository.go): `internal/postgres/repository.go`

### Admin interface

- [Admin dashboard](https://github.com/workweave/router/blob/main/frontend/src/app/(app)/dashboard/page.tsx): `frontend/src/app/(app)/dashboard/page.tsx`
- [Admin API](https://github.com/workweave/router/tree/main/internal/api/admin): `internal/api/admin`

### Other components

- **API client**

## Connections

- API client → HTTP server: sends requests
- HTTP server → Request proxy: routes requests
- Request proxy → Model router: requests decisions
- Request proxy → Provider dispatch: dispatches inference
- Provider dispatch → Provider clients: calls providers
- Request proxy → Identity and auth: uses identity
- Model router → Policy client: consults policy
- Policy client → Policy registry: fetches serving data
- Model router → HMM routing: uses HMM routing
- Request proxy → Provider subscriptions: leases accounts
- Request proxy → Billing: checks or records spend
- Request proxy → Routing analytics: emits outcomes
- Routing analytics → Postgres repositories: persists analytics
- Billing → Postgres repositories: persists billing data
- Admin dashboard → Admin API: calls admin routes
- HTTP server → Admin API: registers admin routes (evidence: `internal/server/server.go`)
- HTTP server → Request proxy: registers metrics handlers (evidence: `internal/server/server.go`)
- Model router → Provider clients: wired at startup
