# nova-liu/nanobot architecture

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

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

## Overview

1. **Repository shape**
   - `nanobot/` is the main Python runtime and package.
   - `webui/` is a separate TypeScript/React frontend for interactive chat.
   - `bridge/` is a separate TypeScript WhatsApp bridge service.
   - `tests/` mirrors the runtime subsystems closely, which is a good clue that the architecture is intentionally modular.

2. **Primary runtime entrypoints**
   - The Python package exposes CLI-style entrypoints for onboarding, chatting, a gateway/websocket mode, and an API server.
   - `nanobot/__main__.py`, `nanobot/cli/`, and `nanobot/api/server.py` are the main operational entrances.
   - `Dockerfile`, `docker-compose.yml`, and `entrypoint.sh` indicate it is designed to run as a long-lived service, not just a library.

3. **Core execution model: one agent loop**
   - The heart of the system is the agent loop in `nanobot/agent/loop.py`, backed by `runner.py`, `context.py`, and `hook.py`.
   - Incoming messages are normalized into a session context, enriched with memory/skills, then sent to an LLM provider.
   - Tool calls, retries, compaction, and lifecycle hooks all happen inside or around this loop rather than in external orchestration code.

4. **Session and persistence boundary**
   - `nanobot/session/manager.py` owns conversation/session state and history.
   - Persistence helpers such as `utils/gitstore.py`, `agent/tools/file_state.py`, and the session-related tests suggest local durable storage is a first-class concern.
   - The design keeps conversation state separate from channel transport, which is important for sharing one agent across many surfaces.

5. **Provider abstraction for model backends**
   - `nanobot/providers/` contains adapters for OpenAI-compatible APIs, Anthropic, Azure OpenAI, GitHub Copilot, and other model backends.
   - `providers/registry.py` selects providers, while `providers/openai_responses/` handles OpenAI Responses-specific parsing and conversions.
   - This is a clean boundary: the agent loop talks to a provider interface, not to vendor SDKs directly.

6. **Tool system as the agent’s action layer**
   - `nanobot/agent/tools/` is a structured tool runtime with a registry, schemas, and base classes.
   - Tools cover filesystem, shell, web search/fetch, sandboxing, notebooks, messaging, spawning subagents, cron, MCP, and self/introspection.
   - The loop delegates external actions through this tool layer, so tool execution is isolated from message transport and model selection.

7. **Skills and prompt composition**
   - `nanobot/skills/` stores reusable skill packages, each with its own `SKILL.md` and, in some cases, helper scripts.
   - `nanobot/templates/` contains the prompt scaffolding for agent identity, tool instructions, memory, heartbeat, and subagent behavior.
   - Skills are injected as context, not as code plugins, which keeps the runtime lightweight while still extensible.

8. **Channel adapters for external chat systems**
   - `nanobot/channels/` defines the channel abstraction and concrete adapters for Slack, Discord, Telegram, Matrix, Feishu, WeCom, WhatsApp, email, WebSocket, and others.
   - `channels/manager.py` and `channels/registry.py` manage fan-in/fan-out and channel discovery.
   - These adapters are the transport boundary: they translate platform-specific events into the unified session/message model, and translate agent output back into platform-specific messages.

9. **WebSocket and WebUI path**
   - The WebUI in `webui/` talks to the Python backend through the WebSocket channel and associated API helpers.
   - `webui/src/hooks/useNanobotStream.ts`, `webui/src/lib/nanobot-client.ts`, and the chat components show that the frontend is a thin client over streamed session updates.
   - This path is separate from the traditional chat-app integrations and is optimized for interactive debugging and local development.

10. **OpenAI-compatible API boundary**
   - `nanobot/api/server.py` exposes an API surface for programmatic use and streaming.
   - The README and tests indicate it supports OpenAI-compatible behavior, including SSE-style streaming in newer versions.
   - This lets nanobot act both as a standalone agent and as a backend for other tooling.

11. **Background services**
   - `nanobot/cron/` schedules recurring tasks and reminders.
   - `nanobot/heartbeat/` keeps long-running sessions and agent state alive.
   - `nanobot/bus/` provides an internal event/queue mechanism for moving events between services without coupling them directly to the channel layer.

12. **Configuration, security, and runtime controls**
   - `nanobot/config/` handles config loading, paths, and schema validation.
   - `nanobot/security/network.py` and the security-oriented tests suggest network/tool access is constrained intentionally.
   - This boundary matters because the agent can execute shell, web, and filesystem actions, so policy and runtime safeguards are part of the architecture rather than an afterthought.

13. **Bridge service**
   - `bridge/` is a separate Node/TypeScript service, with its own package and server, likely used to connect WhatsApp to the Python core.
   - It sits at the edge of the system rather than inside the main agent runtime.
   - Architecturally, this is a transport bridge: external messaging platform on one side, nanobot’s unified message/session model on the other.

14. **Operational view**
   - Typical flow is: channel/API/WebUI input → session manager/context assembly → agent loop → provider call and/or tool execution → streamed response back through the same channel.
   - Cron and heartbeat can inject work independently of user messages.
   - Memory and skills are not separate services; they are contextual inputs that shape the loop and make the agent persistent without heavy orchestration.

Main entry points: [`nanobot/agent/loop.py`](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/loop.py) (Agent loop), [`nanobot/agent/context.py`](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/context.py) (Context), [`nanobot/channels/manager.py`](https://github.com/nova-liu/nanobot/blob/main/nanobot/channels/manager.py) (Channels), [`nanobot/session/manager.py`](https://github.com/nova-liu/nanobot/blob/main/nanobot/session/manager.py) (Session mgr)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python runtime"]
  node_entrypoints["Entrypoints<br/>[__main__.py]"]
  node_cli["CLI<br/>command-line interface<br/>[commands.py]"]
  node_api_server["API server<br/>HTTP/SSE API<br/>[server.py]"]
  node_session_mgr[("Session mgr<br/>session state<br/>[manager.py]")]
  node_agent_loop(("Agent loop<br/>agent orchestration<br/>[loop.py]"))
  node_agent_ctx["Context<br/>turn assembly<br/>[context.py]"]
  node_agent_runner["Runner<br/>loop runtime<br/>[runner.py]"]
  node_providers{{"Providers<br/>LLM adapters<br/>[registry.py]"}}
  node_tools{{"Tool runtime<br/>action layer<br/>[registry.py]"}}
  node_skills["Skills<br/>prompt packages<br/>[README.md]"]
  node_templates["Templates<br/>prompt scaffolding<br/>[AGENTS.md]"]
  node_channels{{"Channels<br/>transport adapters<br/>[manager.py]"}}
  node_bus["Event bus<br/>internal messaging<br/>[queue.py]"]
  node_cron["Cron<br/>scheduled jobs<br/>[service.py]"]
  node_heartbeat["Heartbeat<br/>liveness service<br/>[service.py]"]
  node_config["Config<br/>[loader.py]"]
  node_security["Security<br/>policy boundary<br/>[network.py]"]
end

subgraph group_frontend["Web UI"]
  node_webui_app["Web UI app<br/>React frontend<br/>[App.tsx]"]
  node_webui_stream["Stream client<br/>frontend data flow"]
  node_webui_shell["Chat shell<br/>ui composition<br/>[ThreadShell.tsx]"]
end

subgraph group_bridge["WhatsApp bridge"]
  node_wa_bridge["Bridge server<br/>Node transport bridge<br/>[server.ts]"]
  node_wa_client["WhatsApp adapter<br/>bridge client<br/>[whatsapp.ts]"]
end

node_entrypoints -->|"invokes"| node_cli
node_entrypoints -->|"starts"| node_api_server
node_cli -->|"opens"| node_session_mgr
node_api_server -->|"reads/writes"| node_session_mgr
node_session_mgr -->|"supplies state"| node_agent_ctx
node_agent_ctx -->|"injects"| node_skills
node_agent_ctx -->|"renders"| node_templates
node_agent_ctx -->|"applies policy"| node_security
node_agent_ctx -->|"feeds"| node_agent_loop
node_agent_loop -->|"driven by"| node_agent_runner
node_agent_loop -->|"calls model"| node_providers
node_agent_loop -->|"executes actions"| node_tools
node_tools -->|"emits events"| node_bus
node_cron -->|"schedules work"| node_bus
node_heartbeat -->|"signals"| node_bus
node_channels -->|"attaches to"| node_session_mgr
node_channels -->|"delivers turns"| node_agent_loop
node_agent_loop -->|"streams output"| node_channels
node_webui_app -->|"uses"| node_webui_stream
node_webui_stream -->|"connects via websocket"| node_channels
node_wa_bridge -->|"wraps"| node_wa_client
node_wa_bridge -.->|"relays messages"| node_channels

click node_entrypoints "https://github.com/nova-liu/nanobot/blob/main/nanobot/__main__.py"
click node_cli "https://github.com/nova-liu/nanobot/blob/main/nanobot/cli/commands.py"
click node_api_server "https://github.com/nova-liu/nanobot/blob/main/nanobot/api/server.py"
click node_session_mgr "https://github.com/nova-liu/nanobot/blob/main/nanobot/session/manager.py"
click node_agent_loop "https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/loop.py"
click node_agent_ctx "https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/context.py"
click node_agent_runner "https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/runner.py"
click node_providers "https://github.com/nova-liu/nanobot/blob/main/nanobot/providers/registry.py"
click node_tools "https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/tools/registry.py"
click node_skills "https://github.com/nova-liu/nanobot/blob/main/nanobot/skills/README.md"
click node_templates "https://github.com/nova-liu/nanobot/blob/main/nanobot/templates/AGENTS.md"
click node_channels "https://github.com/nova-liu/nanobot/blob/main/nanobot/channels/manager.py"
click node_bus "https://github.com/nova-liu/nanobot/blob/main/nanobot/bus/queue.py"
click node_cron "https://github.com/nova-liu/nanobot/blob/main/nanobot/cron/service.py"
click node_heartbeat "https://github.com/nova-liu/nanobot/blob/main/nanobot/heartbeat/service.py"
click node_config "https://github.com/nova-liu/nanobot/blob/main/nanobot/config/loader.py"
click node_security "https://github.com/nova-liu/nanobot/blob/main/nanobot/security/network.py"
click node_webui_app "https://github.com/nova-liu/nanobot/blob/main/webui/src/App.tsx"
click node_webui_stream "https://github.com/nova-liu/nanobot/blob/main/webui/src/hooks/useNanobotStream.ts"
click node_webui_shell "https://github.com/nova-liu/nanobot/blob/main/webui/src/components/thread/ThreadShell.tsx"
click node_wa_bridge "https://github.com/nova-liu/nanobot/blob/main/bridge/src/server.ts"
click node_wa_client "https://github.com/nova-liu/nanobot/blob/main/bridge/src/whatsapp.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_entrypoints,node_cli,node_api_server,node_session_mgr,node_agent_loop,node_agent_ctx,node_agent_runner,node_providers,node_tools,node_skills,node_templates,node_channels,node_bus,node_cron,node_heartbeat,node_config,node_security toneBlue
class node_webui_app,node_webui_stream,node_webui_shell toneAmber
class node_wa_bridge,node_wa_client toneMint
```

## Components

### Python runtime

Core nanobot agent system, APIs, channels, and services.

- [Entrypoints](https://github.com/nova-liu/nanobot/blob/main/nanobot/__main__.py): python CLI/service entrypoints · Main operational starts: package entry, CLI, and API server. · `nanobot/__main__.py`
- [CLI](https://github.com/nova-liu/nanobot/blob/main/nanobot/cli/commands.py): command-line interface · User-facing commands for onboarding, chat, and stream modes. · `nanobot/cli/commands.py`
- [API server](https://github.com/nova-liu/nanobot/blob/main/nanobot/api/server.py): HTTP/SSE API · Programmatic and streaming backend surface for external clients. · `nanobot/api/server.py`
- [Session mgr](https://github.com/nova-liu/nanobot/blob/main/nanobot/session/manager.py): session state · Owns conversation state, history, and persistence boundaries. · `nanobot/session/manager.py`
- [Agent loop](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/loop.py): agent orchestration · Central execution loop for turns, retries, compaction, and lifecycle hooks. · `nanobot/agent/loop.py`
- [Context](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/context.py): turn assembly · Builds the per-turn context from messages, memory, skills, and metadata. · `nanobot/agent/context.py`
- [Runner](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/runner.py): loop runtime · Drives loop execution and turn lifecycle. · `nanobot/agent/runner.py`
- [Providers](https://github.com/nova-liu/nanobot/blob/main/nanobot/providers/registry.py): LLM adapters · Vendor-neutral model backend adapters and response parsing boundary. · `nanobot/providers/registry.py`
- [Tool runtime](https://github.com/nova-liu/nanobot/blob/main/nanobot/agent/tools/registry.py): action layer · Registry and execution layer for filesystem, shell, web, messaging, MCP, and subagent tools. · `nanobot/agent/tools/registry.py`
- [Skills](https://github.com/nova-liu/nanobot/blob/main/nanobot/skills/README.md): prompt packages · Reusable skill bundles injected as contextual capability, not plugins. · `nanobot/skills/README.md`
- [Templates](https://github.com/nova-liu/nanobot/blob/main/nanobot/templates/AGENTS.md): prompt scaffolding · Prompt fragments for identity, tools, memory, heartbeat, and subagents. · `nanobot/templates/AGENTS.md`
- [Channels](https://github.com/nova-liu/nanobot/blob/main/nanobot/channels/manager.py): transport adapters · Platform adapters for Slack, Discord, Telegram, Matrix, email, WebSocket, and others. · `nanobot/channels/manager.py`
- [Event bus](https://github.com/nova-liu/nanobot/blob/main/nanobot/bus/queue.py): internal messaging · Internal event/queue mechanism connecting services without tight coupling. · `nanobot/bus/queue.py`
- [Cron](https://github.com/nova-liu/nanobot/blob/main/nanobot/cron/service.py): scheduled jobs · Recurring task scheduling and reminder execution. · `nanobot/cron/service.py`
- [Heartbeat](https://github.com/nova-liu/nanobot/blob/main/nanobot/heartbeat/service.py): liveness service · Keeps long-running sessions and agent state active. · `nanobot/heartbeat/service.py`
- [Config](https://github.com/nova-liu/nanobot/blob/main/nanobot/config/loader.py): runtime config · Loads settings, paths, and schema validation for runtime behavior. · `nanobot/config/loader.py`
- [Security](https://github.com/nova-liu/nanobot/blob/main/nanobot/security/network.py): policy boundary · Network and tool-access constraints for risky runtime capabilities. · `nanobot/security/network.py`

### Web UI

React client for interactive chat and session streaming.

- [Web UI app](https://github.com/nova-liu/nanobot/blob/main/webui/src/App.tsx): React frontend · Interactive chat application for local or remote use. · `webui/src/App.tsx`
- [Stream client](https://github.com/nova-liu/nanobot/blob/main/webui/src/hooks/useNanobotStream.ts): frontend data flow · Hook and client layer for streaming session updates from nanobot. · `webui/src/hooks/useNanobotStream.ts`
- [Chat shell](https://github.com/nova-liu/nanobot/blob/main/webui/src/components/thread/ThreadShell.tsx): ui composition · Thread, sidebar, composer, and message presentation components. · `webui/src/components/thread/ThreadShell.tsx`

### WhatsApp bridge

Separate TypeScript service for WhatsApp transport integration.

- [Bridge server](https://github.com/nova-liu/nanobot/blob/main/bridge/src/server.ts): Node transport bridge · Separate WhatsApp integration service in TypeScript. · `bridge/src/server.ts`
- [WhatsApp adapter](https://github.com/nova-liu/nanobot/blob/main/bridge/src/whatsapp.ts): bridge client · WhatsApp-specific connection and message translation logic. · `bridge/src/whatsapp.ts`

## Connections

- Entrypoints → CLI: invokes · Package entrypoint dispatches to CLI modes.
- Entrypoints → API server: starts · Can run the backend API/server mode.
- CLI → Session mgr: opens · CLI commands interact with stored sessions.
- API server → Session mgr: reads/writes · API requests operate on shared session state.
- Session mgr → Context: supplies state · Conversation history and metadata feed context assembly.
- Context → Skills: injects · Skills are loaded into the turn context.
- Context → Templates: renders · Prompt scaffolding shapes the assembled context.
- Context → Security: applies policy · Tool and network constraints are part of context/runtime setup.
- Context → Agent loop: feeds · Prepared context enters the main execution loop.
- Agent loop → Runner: driven by · Runner controls loop execution and lifecycle.
- Agent loop → Providers: calls model · Loop delegates inference to provider adapters.
- Agent loop → Tool runtime: executes actions · Tool calls are routed through the tool runtime.
- Tool runtime → Event bus: emits events · Tools can publish internal events and results.
- Cron → Event bus: schedules work · Recurring jobs inject work into the internal event flow.
- Heartbeat → Event bus: signals · Heartbeat service keeps active sessions alive through events.
- Channels → Session mgr: attaches to · Transport adapters map platform events onto sessions.
- Channels → Agent loop: delivers turns · Normalized inbound messages trigger agent execution.
- Agent loop → Channels: streams output · Agent responses are sent back through the originating transport.
- Web UI app → Stream client: uses · UI composition is driven by the stream client.
- Stream client → Channels: connects via websocket · Frontend consumes the WebSocket-based backend path.
- Bridge server → WhatsApp adapter: wraps · Bridge server uses WhatsApp-specific integration logic.
- Bridge server → Channels: relays messages · Bridge acts as an edge transport into the unified message model.
