# nimbleway/webrouter architecture

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

- Interactive diagram: https://gitdiagram.com/nimbleway/webrouter
- Repository: https://github.com/nimbleway/webrouter

## Overview

WebRouter is a Python interface for agent web access: callers use one typed API across multiple search, extraction, answer, research, live-data, and browser providers. The primary workflow normalizes a request, selects or routes it to a provider, and returns a provider-independent response; auto routing can fall back when a provider fails. Separate capabilities expose vendor APIs, MCP tools, agent-framework integrations, and benchmarking/evaluation. The graph follows README-documented behavior and sampled/indexed relationships; several capability implementations were not sampled, so their internal links are omitted.

Main entry points: [`src/web_router/client.py`](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client.py) (Router Facade), [`src/web_router/routing`](https://github.com/nimbleway/webrouter/tree/main/src/web_router/routing) (Request Routing), [`src/web_router/client_search.py`](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_search.py) (Search), [`src/web_router/client_live_data.py`](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_live_data.py) (Live Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client["Router Facade<br/>[client.py]"]
  node_search["Search<br/>[client_search.py]"]
  node_live["Live Data"]
  node_plan["Prompt Planning<br/>[client_plan.py]"]
end

subgraph group_route["Routing and Types"]
  node_routing["Request Routing"]
  node_registry["Provider Registry<br/>[registry.py]"]
  node_types["Typed Models<br/>[types.py]"]
  node_decision["Decision Types<br/>[types_decision.py]"]
  node_errors["Error Types<br/>[exceptions.py]"]
end

subgraph group_providers["Provider Access"]
  node_provider_contract["Provider Contract<br/>[base.py]"]
  node_provider_impls["Provider Backends"]
  node_live_impl["Live Data Sources"]
  node_vendor_api["Vendor APIs"]
end

subgraph group_interfaces["Agent Interfaces"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_mcp_tools["MCP Tools<br/>[tools.py]"]
  node_integrations["Agent Integrations"]
  node_cli["Command Line<br/>[commands.py]"]
end

subgraph group_measure["Evaluation"]
  node_benchmark["Benchmarking"]
  node_evals["Evaluation<br/>[run.py]"]
end

node_caller(("Application"))

node_caller -->|"calls"| node_client
node_client -->|"offers search"| node_search
node_client -->|"offers live data"| node_live
node_client -->|"offers planning"| node_plan
node_client -->|"routes requests"| node_routing
node_client -->|"resolves providers"| node_registry
node_search -->|"dispatches calls"| node_routing
node_search -->|"returns models"| node_types
node_live -->|"returns models"| node_types
node_routing -->|"selects backends"| node_registry
node_routing -->|"records decisions"| node_decision
node_routing -->|"invokes providers"| node_provider_contract
node_provider_contract -->|"normalizes responses"| node_types
node_registry -->|"loads providers"| node_provider_impls
node_live -->|"selects sources"| node_live_impl
node_client -->|"supports vendor calls"| node_vendor_api
node_client -->|"offers benchmarks"| node_benchmark
node_benchmark -->|"compares providers"| node_provider_impls
node_benchmark -->|"scores results"| node_evals
node_caller -->|"connects via MCP"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"uses router API"| node_client
node_caller -->|"uses agent tools"| node_integrations
node_integrations -->|"wraps router"| node_client
node_caller -->|"runs commands"| node_cli

click node_client "https://github.com/nimbleway/webrouter/blob/main/src/web_router/client.py"
click node_search "https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_search.py"
click node_live "https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_live_data.py"
click node_plan "https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_plan.py"
click node_routing "https://github.com/nimbleway/webrouter/tree/main/src/web_router/routing"
click node_registry "https://github.com/nimbleway/webrouter/blob/main/src/web_router/registry.py"
click node_types "https://github.com/nimbleway/webrouter/blob/main/src/web_router/types.py"
click node_decision "https://github.com/nimbleway/webrouter/blob/main/src/web_router/types_decision.py"
click node_errors "https://github.com/nimbleway/webrouter/blob/main/src/web_router/exceptions.py"
click node_provider_contract "https://github.com/nimbleway/webrouter/blob/main/src/web_router/providers/base.py"
click node_provider_impls "https://github.com/nimbleway/webrouter/tree/main/src/web_router/providers"
click node_live_impl "https://github.com/nimbleway/webrouter/blob/main/src/web_router/live_data_backends.py"
click node_vendor_api "https://github.com/nimbleway/webrouter/tree/main/src/web_router/vendors"
click node_mcp_server "https://github.com/nimbleway/webrouter/blob/main/src/web_router/mcp/server.py"
click node_mcp_tools "https://github.com/nimbleway/webrouter/blob/main/src/web_router/mcp/tools.py"
click node_integrations "https://github.com/nimbleway/webrouter/tree/main/src/web_router/integrations"
click node_cli "https://github.com/nimbleway/webrouter/blob/main/src/web_router/cli/commands.py"
click node_benchmark "https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_benchmark.py"
click node_evals "https://github.com/nimbleway/webrouter/blob/main/src/web_router/evals/run.py"

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_client,node_search,node_live,node_plan toneBlue
class node_routing,node_registry,node_types,node_decision,node_errors toneAmber
class node_provider_contract,node_provider_impls,node_live_impl,node_vendor_api toneMint
class node_mcp_server,node_mcp_tools,node_integrations,node_cli toneRose
class node_benchmark,node_evals,node_caller toneIndigo
```

## Components

### Client API

- [Router Facade](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client.py): `src/web_router/client.py`
- [Search](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_search.py): `src/web_router/client_search.py`
- [Live Data](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_live_data.py): `src/web_router/client_live_data.py`
- [Prompt Planning](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_plan.py): `src/web_router/client_plan.py`

### Routing and Types

- [Request Routing](https://github.com/nimbleway/webrouter/tree/main/src/web_router/routing): `src/web_router/routing`
- [Provider Registry](https://github.com/nimbleway/webrouter/blob/main/src/web_router/registry.py): `src/web_router/registry.py`
- [Typed Models](https://github.com/nimbleway/webrouter/blob/main/src/web_router/types.py): `src/web_router/types.py`
- [Decision Types](https://github.com/nimbleway/webrouter/blob/main/src/web_router/types_decision.py): `src/web_router/types_decision.py`
- [Error Types](https://github.com/nimbleway/webrouter/blob/main/src/web_router/exceptions.py): `src/web_router/exceptions.py`

### Provider Access

- [Provider Contract](https://github.com/nimbleway/webrouter/blob/main/src/web_router/providers/base.py): `src/web_router/providers/base.py`
- [Provider Backends](https://github.com/nimbleway/webrouter/tree/main/src/web_router/providers): `src/web_router/providers`
- [Live Data Sources](https://github.com/nimbleway/webrouter/blob/main/src/web_router/live_data_backends.py): `src/web_router/live_data_backends.py`
- [Vendor APIs](https://github.com/nimbleway/webrouter/tree/main/src/web_router/vendors): `src/web_router/vendors`

### Agent Interfaces

- [MCP Server](https://github.com/nimbleway/webrouter/blob/main/src/web_router/mcp/server.py): `src/web_router/mcp/server.py`
- [MCP Tools](https://github.com/nimbleway/webrouter/blob/main/src/web_router/mcp/tools.py): `src/web_router/mcp/tools.py`
- [Agent Integrations](https://github.com/nimbleway/webrouter/tree/main/src/web_router/integrations): `src/web_router/integrations`
- [Command Line](https://github.com/nimbleway/webrouter/blob/main/src/web_router/cli/commands.py): `src/web_router/cli/commands.py`

### Evaluation

- [Benchmarking](https://github.com/nimbleway/webrouter/blob/main/src/web_router/client_benchmark.py): `src/web_router/client_benchmark.py`
- [Evaluation](https://github.com/nimbleway/webrouter/blob/main/src/web_router/evals/run.py): `src/web_router/evals/run.py`

### Other components

- **Application**

## Connections

- Application → Router Facade: calls
- Router Facade → Search: offers search (evidence: `src/web_router/client.py`)
- Router Facade → Live Data: offers live data (evidence: `src/web_router/client.py`)
- Router Facade → Prompt Planning: offers planning (evidence: `src/web_router/client.py`)
- Router Facade → Request Routing: routes requests (evidence: `src/web_router/client.py`)
- Router Facade → Provider Registry: resolves providers (evidence: `src/web_router/client.py`)
- Search → Request Routing: dispatches calls (evidence: `src/web_router/client_search.py`)
- Search → Typed Models: returns models (evidence: `src/web_router/client_search.py`)
- Live Data → Typed Models: returns models (evidence: `src/web_router/client_live_data.py`)
- Request Routing → Provider Registry: selects backends (evidence: `src/web_router/registry.py`)
- Request Routing → Decision Types: records decisions (evidence: `src/web_router/routing/contract.py`)
- Request Routing → Provider Contract: invokes providers (evidence: `src/web_router/providers/base.py`)
- Provider Contract → Typed Models: normalizes responses (evidence: `src/web_router/providers/base.py`)
- Provider Registry → Provider Backends: loads providers (evidence: `src/web_router/registry.py`)
- Live Data → Live Data Sources: selects sources (evidence: `src/web_router/client_live_data.py`)
- Router Facade → Vendor APIs: supports vendor calls
- Router Facade → Benchmarking: offers benchmarks (evidence: `src/web_router/client.py`)
- Benchmarking → Provider Backends: compares providers (evidence: `src/web_router/client_benchmark.py`)
- Benchmarking → Evaluation: scores results (evidence: `src/web_router/client_benchmark.py`)
- Application → MCP Server: connects via MCP
- MCP Server → MCP Tools: dispatches tools (evidence: `src/web_router/mcp/server.py`)
- MCP Tools → Router Facade: uses router API
- Application → Agent Integrations: uses agent tools
- Agent Integrations → Router Facade: wraps router (evidence: `src/web_router/integrations/langchain.py`)
- Application → Command Line: runs commands
