# baharul0111/toolrouter architecture

> Architecture diagram of the GitHub repository baharul0111/toolrouter, 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/baharul0111/toolrouter
- Repository: https://github.com/baharul0111/toolrouter

## Overview

ToolRouter is a local AI assistant that discovers MCP tools, indexes their descriptions, retrieves a small task-specific set, and lets a local LLM call those tools. The main request path runs through the API and service into the agent loop; the loop retrieves tools, validates and gates proposed calls, dispatches approved calls through MCP, then can search again between steps. The README documents gateway mode, a web UI, and optional Phoenix tracing. Some subsystem wiring is based on README documentation because those source excerpts were not sampled.

Main entry points: [`toolrouter/agent/loop.py`](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/loop.py) (Agent loop), [`toolrouter/service.py`](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/service.py) (Service coordinator), [`toolrouter/retrieval/pipeline.py`](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/pipeline.py) (Retrieval pipeline), [`toolrouter/api/main.py`](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/api/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_ui["Web UI<br/>[app.py]"]
  node_api["HTTP API<br/>[main.py]"]
  node_gateway["MCP gateway<br/>[gateway.py]"]
end

subgraph group_core["Assistant runtime"]
  node_service["Service coordinator<br/>[service.py]"]
  node_agent["Agent loop<br/>[loop.py]"]
  node_prompt["Prompt builder<br/>[prompt.py]"]
  node_validator["Input validator<br/>[validator.py]"]
  node_safety["Safety checks<br/>[safety.py]"]
  node_store[("Run and cache store<br/>[db.py]")]
end

subgraph group_catalog["Tool catalog"]
  node_registry["Tool registry<br/>[sync.py]"]
  node_enricher["Tool enrichment<br/>[enrich.py]"]
  node_indexbuild["Index builder<br/>[build_index.py]"]
  node_buddies["Tool pair graph<br/>[buddy_graph.py]"]
end

subgraph group_search["Tool retrieval"]
  node_retriever["Retrieval pipeline<br/>[pipeline.py]"]
  node_dense["Semantic search<br/>[dense.py]"]
  node_bm25["Keyword search<br/>[bm25.py]"]
  node_fusion["Rank fusion<br/>[fusion.py]"]
  node_reranker["Candidate reranker<br/>[reranker.py]"]
  node_selector["Adaptive selector<br/>[selector.py]"]
end

subgraph group_integrations["Models and tools"]
  node_mcp["MCP client pool<br/>[pool.py]"]
  node_servers["MCP tool servers"]
  node_ollama["Ollama LLM"]
  node_qdrant[("Qdrant index")]
  node_phoenix["Phoenix tracing"]
end

node_user(("User"))

node_user -->|"submits request"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"uses service"| node_service
node_api -->|"runs and resumes"| node_agent
node_api -->|"reads run history"| node_store
node_service -->|"starts and lists tools"| node_mcp
node_service -->|"syncs listings"| node_registry
node_service -->|"builds index"| node_indexbuild
node_service -->|"creates agent"| node_agent
node_service -->|"creates store"| node_store
node_service -.->|"configures tracing"| node_phoenix
node_registry -->|"enriches cards"| node_enricher
node_registry -->|"caches enrichment"| node_store
node_indexbuild -->|"populates index"| node_retriever
node_retriever -->|"runs semantic search"| node_dense
node_retriever -->|"runs keyword search"| node_bm25
node_retriever -->|"merges rankings"| node_fusion
node_retriever -->|"rescores candidates"| node_reranker
node_retriever -->|"selects tools"| node_selector
node_retriever -->|"adds paired tools"| node_buddies
node_dense -->|"searches vectors"| node_qdrant
node_agent -->|"searches per step"| node_retriever
node_agent -->|"builds prompt"| node_prompt
node_agent -->|"requests responses"| node_ollama
node_agent -->|"checks arguments"| node_validator
node_agent -->|"checks risky calls"| node_safety
node_agent -->|"calls approved tools"| node_mcp
node_agent -->|"records runs"| node_store
node_mcp -->|"lists and calls tools"| node_servers
node_gateway -->|"uses service"| node_service
node_gateway -->|"serves MCP clients"| node_user

click node_ui "https://github.com/baharul0111/toolrouter/blob/main/ui/app.py"
click node_api "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/api/main.py"
click node_gateway "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/gateway.py"
click node_service "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/service.py"
click node_agent "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/loop.py"
click node_prompt "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/prompt.py"
click node_validator "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/validator.py"
click node_safety "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/safety.py"
click node_store "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/db.py"
click node_registry "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/registry/sync.py"
click node_enricher "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/enrich.py"
click node_indexbuild "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/build_index.py"
click node_buddies "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/buddy_graph.py"
click node_retriever "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/pipeline.py"
click node_dense "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/dense.py"
click node_bm25 "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/bm25.py"
click node_fusion "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/fusion.py"
click node_reranker "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/reranker.py"
click node_selector "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/selector.py"
click node_mcp "https://github.com/baharul0111/toolrouter/blob/main/toolrouter/mcp_client/pool.py"
click node_servers "https://github.com/baharul0111/toolrouter/tree/main/servers"

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_ui,node_api,node_gateway,node_user toneBlue
class node_service,node_agent,node_prompt,node_validator,node_safety,node_store toneAmber
class node_registry,node_enricher,node_indexbuild,node_buddies toneMint
class node_retriever,node_dense,node_bm25,node_fusion,node_reranker,node_selector toneRose
class node_mcp,node_servers,node_ollama,node_qdrant,node_phoenix toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/baharul0111/toolrouter/blob/main/ui/app.py): `ui/app.py`
- [HTTP API](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/api/main.py): `toolrouter/api/main.py`
- [MCP gateway](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/gateway.py): `toolrouter/gateway.py`

### Assistant runtime

- [Service coordinator](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/service.py): `toolrouter/service.py`
- [Agent loop](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/loop.py): `toolrouter/agent/loop.py`
- [Prompt builder](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/prompt.py): `toolrouter/agent/prompt.py`
- [Input validator](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/validator.py): `toolrouter/agent/validator.py`
- [Safety checks](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/agent/safety.py): `toolrouter/agent/safety.py`
- [Run and cache store](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/db.py): `toolrouter/db.py`

### Tool catalog

- [Tool registry](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/registry/sync.py): `toolrouter/registry/sync.py`
- [Tool enrichment](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/enrich.py): `toolrouter/indexing/enrich.py`
- [Index builder](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/build_index.py): `toolrouter/indexing/build_index.py`
- [Tool pair graph](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/indexing/buddy_graph.py): `toolrouter/indexing/buddy_graph.py`

### Tool retrieval

- [Retrieval pipeline](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/pipeline.py): `toolrouter/retrieval/pipeline.py`
- [Semantic search](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/dense.py): `toolrouter/retrieval/dense.py`
- [Keyword search](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/bm25.py): `toolrouter/retrieval/bm25.py`
- [Rank fusion](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/fusion.py): `toolrouter/retrieval/fusion.py`
- [Candidate reranker](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/reranker.py): `toolrouter/retrieval/reranker.py`
- [Adaptive selector](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/retrieval/selector.py): `toolrouter/retrieval/selector.py`

### Models and tools

- [MCP client pool](https://github.com/baharul0111/toolrouter/blob/main/toolrouter/mcp_client/pool.py): `toolrouter/mcp_client/pool.py`
- [MCP tool servers](https://github.com/baharul0111/toolrouter/tree/main/servers): `servers`
- **Ollama LLM**
- **Qdrant index**
- **Phoenix tracing**

### Other components

- **User**

## Connections

- User → Web UI: submits request
- Web UI → HTTP API: sends requests
- HTTP API → Service coordinator: uses service
- HTTP API → Agent loop: runs and resumes
- HTTP API → Run and cache store: reads run history
- Service coordinator → MCP client pool: starts and lists tools
- Service coordinator → Tool registry: syncs listings
- Service coordinator → Index builder: builds index
- Service coordinator → Agent loop: creates agent
- Service coordinator → Run and cache store: creates store
- Service coordinator → Phoenix tracing: configures tracing
- Tool registry → Tool enrichment: enriches cards
- Tool registry → Run and cache store: caches enrichment
- Index builder → Retrieval pipeline: populates index
- Retrieval pipeline → Semantic search: runs semantic search
- Retrieval pipeline → Keyword search: runs keyword search
- Retrieval pipeline → Rank fusion: merges rankings
- Retrieval pipeline → Candidate reranker: rescores candidates
- Retrieval pipeline → Adaptive selector: selects tools
- Retrieval pipeline → Tool pair graph: adds paired tools
- Semantic search → Qdrant index: searches vectors
- Agent loop → Retrieval pipeline: searches per step
- Agent loop → Prompt builder: builds prompt
- Agent loop → Ollama LLM: requests responses
- Agent loop → Input validator: checks arguments
- Agent loop → Safety checks: checks risky calls
- Agent loop → MCP client pool: calls approved tools
- Agent loop → Run and cache store: records runs
- MCP client pool → MCP tool servers: lists and calls tools
- MCP gateway → Service coordinator: uses service
- MCP gateway → User: serves MCP clients