# zaws77/nanobot architecture

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

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

## Overview

##### Project Type & Purpose
- This is an open-source, CLI-based “ultra-lightweight personal AI assistant”
- Core functionality lives in a Python package (`nanobot/`), with a small TypeScript “bridge” (`bridge/`) for WhatsApp Web integration
- It provides:
- A CLI (`nanobot gateway`, `nanobot agent`, etc.)
- Pluggable channel adapters (Telegram, Discord, Slack, Email, QQ, Feishu, DingTalk, WhatsApp, etc.)
- A provider registry for LLM backends (OpenRouter, OpenAI, Claude, vLLM, etc.)
- Tools/skills (filesystem, shell, cron jobs, web search, GitHub, weather, tmux, etc.)
- Scheduling (cron), heartbeat (periodic wake-ups), memory & session management

##### File Structure Analysis
- Top level:
- Dockerfile, .dockerignore / .gitignore, CLI entry (`pyproject.toml`), tests, workspace docs
- `bridge/`: TypeScript service to connect WhatsApp → Python (Node.js ≥18, uses `bridge/src/{index,server,whatsapp}.ts`)
- `nanobot/`: Python package
- Inside `nanobot/`:
├── cli/         (Typer/argparse commands)
├── config/      (Pydantic schemas, loader)
├── session/     (Session manager)
├── bus/         (Event bus & queue)
├── channels/    (One module per chat platform + manager)
├── providers/   (Base classes + registry + built-in providers)
├── agent/       (Core agent logic: prompt context, loop, memory, subagents, tools)
├── skills/      (Bundled skill definitions)
├── cron/        (Scheduled jobs service)
├── heartbeat/   (Periodic wake-up service)
└── utils/       (Helpers)
- Config & workspace in `~/.nanobot/` (~/config.json, workspaces, memory)
- Tests validate channels, tools, Docker behavior

##### README Insights
- Emphasizes plug-in registry patterns (channels, providers, tools)
- Shows Docker and local vLLM support

## Diagram (Mermaid)

```mermaid
graph TB
    %% I/O Layer
    subgraph "I/O Layer"
        CLI["CLI / Gateway"]:::core
        Bridge["WhatsApp Bridge"]:::bridge
    end

    %% Channel Adapters
    subgraph "Channel Adapters & Manager"
        ChanMgr["Channel Manager"]:::core
        subgraph "Adapters"
            Tel["Telegram Adapter"]:::core
            Dis["Discord Adapter"]:::core
            Slack["Slack Adapter"]:::core
            Email["Email Adapter"]:::core
            QQ["QQ Adapter"]:::core
            Feishu["Feishu Adapter"]:::core
            DingTalk["DingTalk Adapter"]:::core
            WA["WhatsApp Adapter"]:::core
        end
    end

    %% Core Services
    Bus["Event Bus & Queue"]:::core
    subgraph "Core Agent Engine"
        AgentLoop["Agent Loop"]:::core
        Context["Context Builder"]:::core
        SubAgent["Subagent"]:::core
        AgentMem["Agent Memory"]:::core
    end

    %% Tools & Skills
    subgraph "Tools & Skills"
        ToolsReg["Tools Registry"]:::tools
        FS["Filesystem Tool"]:::tools
        Shell["Shell Tool"]:::tools
        CronTool["Cron Tool"]:::tools
        MsgTool["Message Tool"]:::tools
        WebTool["Web Tool"]:::tools
        Spawn["Spawn Tool"]:::tools
        Skills["Skills (SKILL.md)"]:::tools
    end

    %% Providers
    subgraph "Provider Registry & Connectors"
        ProvReg["Provider Registry"]:::core
        BaseProv["Provider Base"]:::core
        Litel["Litellm Provider"]:::core
        Trans["Transcription"]:::core
    end

    %% Session & Persistence
    Sess["Session Manager"]:::core
    Persistence["Workspace Dir & Config"]:::storage
    subgraph "Config"
        ConfigLoader["Config Loader"]:::core
        ConfigSchema["Config Schema"]:::core
    end

    %% Aux Services
    CronSvc["Cron Service"]:::aux
    Heartbeat["Heartbeat Service"]:::aux

    %% External Systems
    subgraph "External Systems"
        ChatExt["Chat Servers\n(Telegram, Discord,\nSlack, Email, QQ,\nFeishu, DingTalk, WhatsApp)"]:::external
        LLM["LLM Endpoints"]:::external
    end

    %% Data Flow
    CLI -->|"invoke"| ChanMgr
    Bridge -->|"message"| ChanMgr
    ChanMgr -->|"incoming"| Bus
    CronSvc -.->|"scheduled event"| Bus
    Heartbeat -.->|"heartbeat event"| Bus
    Bus -->|"trigger"| AgentLoop
    AgentLoop --> Context
    AgentLoop --> SubAgent
    AgentLoop --> AgentMem
    AgentLoop -->|"use"| ProvReg
    ProvReg --> LLM
    AgentLoop -->|"invoke"| ToolsReg
    ToolsReg --> FS
    ToolsReg --> Shell
    ToolsReg --> CronTool
    ToolsReg --> MsgTool
    ToolsReg --> WebTool
    ToolsReg --> Spawn
    ToolsReg --> Skills
    AgentLoop --> Sess
    SessionSave[/"Save Session"/]:::storage
    AgentMem --> SessionSave
    Sess --> SessionSave
    AgentLoop -->|"output"| Bus
    Bus -->|"outgoing"| ChanMgr
    ChanMgr --> ChatExt

    ConfigLoader -->|"load"| Persistence
    ConfigSchema --> Persistence

    %% Click Events
    click CLI "https://github.com/zaws77/nanobot/blob/main/nanobot/__main__.py"
    click CLI "https://github.com/zaws77/nanobot/blob/main/nanobot/cli/commands.py"
    click Bridge "https://github.com/zaws77/nanobot/blob/main/bridge/src/index.ts"
    click Bridge "https://github.com/zaws77/nanobot/blob/main/bridge/src/server.ts"
    click Bridge "https://github.com/zaws77/nanobot/blob/main/bridge/src/whatsapp.ts"
    click ChanMgr "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/manager.py"
    click Tel "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/telegram.py"
    click Dis "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/discord.py"
    click Slack "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/slack.py"
    click Email "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/email.py"
    click QQ "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/qq.py"
    click Feishu "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/feishu.py"
    click DingTalk "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/dingtalk.py"
    click WA "https://github.com/zaws77/nanobot/blob/main/nanobot/channels/whatsapp.py"
    click Bus "https://github.com/zaws77/nanobot/blob/main/nanobot/bus/events.py"
    click Bus "https://github.com/zaws77/nanobot/blob/main/nanobot/bus/queue.py"
    click Context "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/context.py"
    click AgentLoop "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/loop.py"
    click AgentMem "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/memory.py"
    click SubAgent "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/subagent.py"
    click ToolsReg "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/registry.py"
    click FS "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/filesystem.py"
    click Shell "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/shell.py"
    click CronTool "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/cron.py"
    click MsgTool "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/message.py"
    click WebTool "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/web.py"
    click Spawn "https://github.com/zaws77/nanobot/blob/main/nanobot/agent/tools/spawn.py"
    click Skills "https://github.com/zaws77/nanobot/tree/main/nanobot/skills/"
    click ProvReg "https://github.com/zaws77/nanobot/blob/main/nanobot/providers/registry.py"
    click BaseProv "https://github.com/zaws77/nanobot/blob/main/nanobot/providers/base.py"
    click Litel "https://github.com/zaws77/nanobot/blob/main/nanobot/providers/litellm_provider.py"
    click Trans "https://github.com/zaws77/nanobot/blob/main/nanobot/providers/transcription.py"
    click Sess "https://github.com/zaws77/nanobot/blob/main/nanobot/session/manager.py"
    click ConfigLoader "https://github.com/zaws77/nanobot/blob/main/nanobot/config/loader.py"
    click ConfigSchema "https://github.com/zaws77/nanobot/blob/main/nanobot/config/schema.py"
    click CronSvc "https://github.com/zaws77/nanobot/blob/main/nanobot/cron/service.py"
    click Heartbeat "https://github.com/zaws77/nanobot/blob/main/nanobot/heartbeat/service.py"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef bridge fill:#FFE5B4,stroke:#d97706,color:#7c2d12
    classDef tools fill:#FFD4D4,stroke:#b91c1c,color:#b91c1c
    classDef aux fill:#FFF4C1,stroke:#d69e2e,color:#b45309
    classDef external fill:#C6F6D5,stroke:#047857,color:#065f46
    classDef storage fill:#E2E8F0,stroke:#475569,color:#1e293b
```
