# drxikunzhao/nanobot architecture

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

- Interactive diagram: https://gitdiagram.com/drxikunzhao/nanobot
- Repository: https://github.com/drxikunzhao/nanobot

## Overview

Nanobot is a self-hosted personal AI agent runtime with WebUI, terminal, chat-channel, and OpenAI-compatible API entry points. The main workflow accepts a user turn, runs the agent with model and tool capabilities, persists session context, and returns a response through the originating surface. Additional documented capabilities include long-term memory, scheduled automation, multi-agent delegation, MCP integrations, and an SDK. The graph combines README-level product scope with sampled implementation evidence; unsampled subsystem wiring is represented conservatively.

Main entry points: [`nanobot/agent/loop.py`](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/loop.py) (Agent loop), [`nanobot/gateway/runtime.py`](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/gateway/runtime.py) (Gateway runtime), [`nanobot/bus/queue.py`](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/bus/queue.py) (Message bus), [`nanobot/channels/manager.py`](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/channels/manager.py) (Chat channels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_webui["WebUI<br/>[App.tsx]"]
  node_terminal["Terminal UI<br/>[app.ts]"]
  node_channels["Chat channels<br/>[manager.py]"]
  node_api["OpenAI API<br/>[server.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_gateway["Gateway runtime<br/>[runtime.py]"]
  node_bus["Message bus<br/>[queue.py]"]
  node_agent["Agent loop<br/>[loop.py]"]
end

subgraph group_models["Models and tools"]
  node_provider["Model routing<br/>[factory.py]"]
  node_tools["Agent tools<br/>[loader.py]"]
  node_delegation["Subagents<br/>[subagent.py]"]
end

subgraph group_state["State and automation"]
  node_sessions[("Session manager<br/>[manager.py]")]
  node_memory["Long-term memory<br/>[memory.py]"]
  node_automation["Scheduled automation<br/>[service.py]"]
  node_goals["Long-horizon goals<br/>[goal_state.py]"]
end

subgraph group_integrations["Integrations"]
  node_mcp["MCP integration<br/>[mcp.py]"]
  node_websearch["Web search<br/>[search.py]"]
  node_imagegen["Image generation"]
  node_sdk["Python SDK<br/>[runtime.py]"]
end

node_user(("User"))
node_modelservice{{"LLM providers"}}
node_chatservice{{"Chat services"}}

node_user -->|"sends turn"| node_webui
node_user -->|"sends turn"| node_terminal
node_user -->|"sends message"| node_channels
node_user -->|"sends request"| node_api
node_webui -->|"connects"| node_gateway
node_terminal -->|"connects"| node_gateway
node_channels -->|"dispatches messages"| node_bus
node_gateway -->|"coordinates runtime"| node_bus
node_api -->|"runs request"| node_agent
node_bus -->|"delivers turn"| node_agent
node_agent -->|"requests completion"| node_provider
node_provider -->|"calls model"| node_modelservice
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"reads and writes"| node_sessions
node_agent -->|"uses memory"| node_memory
node_agent -->|"delegates work"| node_delegation
node_agent -->|"supports goals"| node_goals
node_automation -->|"starts turns"| node_agent
node_channels -->|"connects"| node_chatservice
node_tools -->|"exposes integration"| node_mcp
node_tools -->|"exposes search"| node_websearch
node_agent -->|"requests images"| node_imagegen
node_sdk -.->|"uses runtime"| node_gateway
node_agent -->|"publishes response"| node_bus

click node_webui "https://github.com/drxikunzhao/nanobot/blob/main/webui/src/App.tsx"
click node_terminal "https://github.com/drxikunzhao/nanobot/blob/main/tui/src/app.ts"
click node_channels "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/channels/manager.py"
click node_api "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/api/server.py"
click node_gateway "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/gateway/runtime.py"
click node_bus "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/bus/queue.py"
click node_agent "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/loop.py"
click node_sessions "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/session/manager.py"
click node_memory "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/memory.py"
click node_automation "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/cron/service.py"
click node_goals "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/session/goal_state.py"
click node_provider "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/providers/factory.py"
click node_tools "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/loader.py"
click node_delegation "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/subagent.py"
click node_mcp "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/mcp.py"
click node_websearch "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/search.py"
click node_imagegen "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/providers/image_generation.py"
click node_sdk "https://github.com/drxikunzhao/nanobot/blob/main/nanobot/sdk/runtime.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_webui,node_terminal,node_channels,node_api,node_user toneBlue
class node_gateway,node_bus,node_agent toneAmber
class node_provider,node_tools,node_delegation toneMint
class node_sessions,node_memory,node_automation,node_goals toneRose
class node_mcp,node_websearch,node_imagegen,node_sdk,node_modelservice,node_chatservice toneIndigo
```

## Components

### User surfaces

- [WebUI](https://github.com/drxikunzhao/nanobot/blob/main/webui/src/App.tsx): `webui/src/App.tsx`
- [Terminal UI](https://github.com/drxikunzhao/nanobot/blob/main/tui/src/app.ts): `tui/src/app.ts`
- [Chat channels](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/channels/manager.py): `nanobot/channels/manager.py`
- [OpenAI API](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/api/server.py): `nanobot/api/server.py`

### Agent runtime

- [Gateway runtime](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/gateway/runtime.py): `nanobot/gateway/runtime.py`
- [Message bus](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/bus/queue.py): `nanobot/bus/queue.py`
- [Agent loop](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/loop.py): `nanobot/agent/loop.py`

### Models and tools

- [Model routing](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/providers/factory.py): `nanobot/providers/factory.py`
- [Agent tools](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/loader.py): `nanobot/agent/tools/loader.py`
- [Subagents](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/subagent.py): `nanobot/agent/subagent.py`

### State and automation

- [Session manager](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/session/manager.py): `nanobot/session/manager.py`
- [Long-term memory](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/memory.py): `nanobot/agent/memory.py`
- [Scheduled automation](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/cron/service.py): `nanobot/cron/service.py`
- [Long-horizon goals](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/session/goal_state.py): `nanobot/session/goal_state.py`

### Integrations

- [MCP integration](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/mcp.py): `nanobot/agent/tools/mcp.py`
- [Web search](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/agent/tools/search.py): `nanobot/agent/tools/search.py`
- [Image generation](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/providers/image_generation.py): `nanobot/providers/image_generation.py`
- [Python SDK](https://github.com/drxikunzhao/nanobot/blob/main/nanobot/sdk/runtime.py): `nanobot/sdk/runtime.py`

### Other components

- **User**
- **LLM providers**
- **Chat services**

## Connections

- User → WebUI: sends turn
- User → Terminal UI: sends turn
- User → Chat channels: sends message
- User → OpenAI API: sends request
- WebUI → Gateway runtime: connects
- Terminal UI → Gateway runtime: connects
- Chat channels → Message bus: dispatches messages
- Gateway runtime → Message bus: coordinates runtime
- OpenAI API → Agent loop: runs request
- Message bus → Agent loop: delivers turn
- Agent loop → Model routing: requests completion
- Model routing → LLM providers: calls model
- Agent loop → Agent tools: dispatches tools
- Agent loop → Session manager: reads and writes
- Agent loop → Long-term memory: uses memory
- Agent loop → Subagents: delegates work
- Agent loop → Long-horizon goals: supports goals
- Scheduled automation → Agent loop: starts turns
- Chat channels → Chat services: connects
- Agent tools → MCP integration: exposes integration
- Agent tools → Web search: exposes search
- Agent loop → Image generation: requests images
- Python SDK → Gateway runtime: uses runtime
- Agent loop → Message bus: publishes response