# stephengpope/thepopebot architecture

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

- Interactive diagram: https://gitdiagram.com/stephengpope/thepopebot
- Repository: https://github.com/stephengpope/thepopebot

## Overview

thepopebot combines authenticated web and Telegram chat, configurable LLM/coding agents, persistent coding workspaces, and background agent jobs. The central workflow is a user message routed through the event handler to the AI runtime, which streams a response and can work in a repository; a separate job path runs work in Docker and returns results through GitHub/Telegram. The graph also shows code, cluster, and configuration capabilities. Some connections are documented in the README; unsampled implementations are represented conservatively.

Main entry points: [`lib/ai/index.js`](https://github.com/stephengpope/thepopebot/blob/main/lib/ai/index.js) (AI runtime), [`api/index.js`](https://github.com/stephengpope/thepopebot/blob/main/api/index.js) (Event handler API), [`lib/tools/docker.js`](https://github.com/stephengpope/thepopebot/blob/main/lib/tools/docker.js) (Docker execution), [`lib/tools/create-agent-job.js`](https://github.com/stephengpope/thepopebot/blob/main/lib/tools/create-agent-job.js) (Agent jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web_chat["Web chat<br/>[chat.jsx]"]
  node_chat_actions["Chat actions<br/>[actions.js]"]
  node_api["Event handler API<br/>[index.js]"]
  node_telegram["Telegram adapter<br/>[telegram.js]"]
  node_auth["Authentication<br/>[index.js]"]
end

subgraph group_runtime["Agent runtime"]
  node_ai["AI runtime<br/>[index.js]"]
  node_agent_adapters["Agent adapters<br/>[claude-code.js]"]
  node_helper_llm["Helper LLM<br/>[helper-llm.js]"]
  node_providers["LLM providers<br/>[llm-providers.js]"]
  node_session["Session persistence<br/>[session-manager.js]"]
end

subgraph group_work["Work execution"]
  node_workspaces["Code workspaces<br/>[actions.js]"]
  node_docker["Docker execution<br/>[docker.js]"]
  node_agent_job["Agent jobs"]
  node_github["GitHub integration<br/>[github.js]"]
  node_clusters["Cluster runtime<br/>[runtime.js]"]
  node_triggers["Triggers and cron<br/>[triggers.js]"]
end

subgraph group_platform["Platform services"]
  node_config["Configuration resolver<br/>[config.js]"]
  node_db_config["Settings storage<br/>[config.js]"]
  node_database[("SQLite database<br/>[index.js]")]
  node_schema["Data schema<br/>[schema.js]"]
end

node_browser(("Browser user"))
node_telegram_user(("Telegram user"))
node_sqlite[("SQLite")]
node_docker_service["Docker service"]
node_github_service["GitHub"]
node_llm_service["LLM provider"]

node_browser -->|"uses"| node_web_chat
node_telegram_user -->|"messages"| node_telegram
node_web_chat -.->|"initiates"| node_chat_actions
node_chat_actions -->|"calls"| node_ai
node_api -->|"calls"| node_ai
node_api -->|"creates"| node_agent_job
node_api -->|"uses"| node_telegram
node_api -.->|"authenticates"| node_auth
node_telegram -->|"webhook"| node_api
node_ai -->|"dispatches"| node_agent_adapters
node_ai -->|"calls"| node_helper_llm
node_ai -->|"reads/writes"| node_session
node_ai -->|"gets workspace"| node_docker
node_ai -.->|"uses configuration"| node_providers
node_workspaces -.->|"manages workspace"| node_docker
node_agent_job -->|"launches container"| node_docker
node_agent_job -->|"opens PR"| node_github
node_github -->|"pushes and merges"| node_github_service
node_api -->|"fetches job logs"| node_github
node_clusters -.->|"runs workers"| node_docker
node_triggers -.->|"schedules work"| node_agent_job
node_config -->|"reads settings"| node_db_config
node_config -->|"resolves models"| node_providers
node_docker -->|"reads settings"| node_config
node_docker -->|"runs containers"| node_docker_service
node_providers -.->|"configures access"| node_llm_service
node_database -->|"opens"| node_sqlite
node_database -->|"uses schema"| node_schema
node_db_config -->|"queries"| node_database

click node_web_chat "https://github.com/stephengpope/thepopebot/blob/main/lib/chat/components/chat.jsx"
click node_chat_actions "https://github.com/stephengpope/thepopebot/blob/main/lib/chat/actions.js"
click node_api "https://github.com/stephengpope/thepopebot/blob/main/api/index.js"
click node_telegram "https://github.com/stephengpope/thepopebot/blob/main/lib/channels/telegram.js"
click node_auth "https://github.com/stephengpope/thepopebot/blob/main/lib/auth/index.js"
click node_ai "https://github.com/stephengpope/thepopebot/blob/main/lib/ai/index.js"
click node_agent_adapters "https://github.com/stephengpope/thepopebot/blob/main/lib/ai/sdk-adapters/claude-code.js"
click node_helper_llm "https://github.com/stephengpope/thepopebot/blob/main/lib/ai/helper-llm.js"
click node_providers "https://github.com/stephengpope/thepopebot/blob/main/lib/llm-providers.js"
click node_session "https://github.com/stephengpope/thepopebot/blob/main/lib/ai/session-manager.js"
click node_workspaces "https://github.com/stephengpope/thepopebot/blob/main/lib/code/actions.js"
click node_docker "https://github.com/stephengpope/thepopebot/blob/main/lib/tools/docker.js"
click node_agent_job "https://github.com/stephengpope/thepopebot/blob/main/lib/tools/create-agent-job.js"
click node_github "https://github.com/stephengpope/thepopebot/blob/main/lib/tools/github.js"
click node_clusters "https://github.com/stephengpope/thepopebot/blob/main/lib/cluster/runtime.js"
click node_triggers "https://github.com/stephengpope/thepopebot/blob/main/lib/triggers.js"
click node_config "https://github.com/stephengpope/thepopebot/blob/main/lib/config.js"
click node_db_config "https://github.com/stephengpope/thepopebot/blob/main/lib/db/config.js"
click node_database "https://github.com/stephengpope/thepopebot/blob/main/lib/db/index.js"
click node_schema "https://github.com/stephengpope/thepopebot/blob/main/lib/db/schema.js"

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_web_chat,node_chat_actions,node_api,node_telegram,node_auth,node_browser,node_telegram_user toneBlue
class node_ai,node_agent_adapters,node_helper_llm,node_providers,node_session,node_sqlite toneAmber
class node_workspaces,node_docker,node_agent_job,node_github,node_clusters,node_triggers toneMint
class node_config,node_db_config,node_database,node_schema toneRose
class node_docker_service,node_github_service,node_llm_service toneIndigo
```

## Components

### User interfaces

- [Web chat](https://github.com/stephengpope/thepopebot/blob/main/lib/chat/components/chat.jsx): `lib/chat/components/chat.jsx`
- [Chat actions](https://github.com/stephengpope/thepopebot/blob/main/lib/chat/actions.js): `lib/chat/actions.js`
- [Event handler API](https://github.com/stephengpope/thepopebot/blob/main/api/index.js): `api/index.js`
- [Telegram adapter](https://github.com/stephengpope/thepopebot/blob/main/lib/channels/telegram.js): `lib/channels/telegram.js`
- [Authentication](https://github.com/stephengpope/thepopebot/blob/main/lib/auth/index.js): `lib/auth/index.js`

### Agent runtime

- [AI runtime](https://github.com/stephengpope/thepopebot/blob/main/lib/ai/index.js): `lib/ai/index.js`
- [Agent adapters](https://github.com/stephengpope/thepopebot/blob/main/lib/ai/sdk-adapters/claude-code.js): `lib/ai/sdk-adapters/claude-code.js`
- [Helper LLM](https://github.com/stephengpope/thepopebot/blob/main/lib/ai/helper-llm.js): `lib/ai/helper-llm.js`
- [LLM providers](https://github.com/stephengpope/thepopebot/blob/main/lib/llm-providers.js): `lib/llm-providers.js`
- [Session persistence](https://github.com/stephengpope/thepopebot/blob/main/lib/ai/session-manager.js): `lib/ai/session-manager.js`

### Work execution

- [Code workspaces](https://github.com/stephengpope/thepopebot/blob/main/lib/code/actions.js): `lib/code/actions.js`
- [Docker execution](https://github.com/stephengpope/thepopebot/blob/main/lib/tools/docker.js): `lib/tools/docker.js`
- [Agent jobs](https://github.com/stephengpope/thepopebot/blob/main/lib/tools/create-agent-job.js): `lib/tools/create-agent-job.js`
- [GitHub integration](https://github.com/stephengpope/thepopebot/blob/main/lib/tools/github.js): `lib/tools/github.js`
- [Cluster runtime](https://github.com/stephengpope/thepopebot/blob/main/lib/cluster/runtime.js): `lib/cluster/runtime.js`
- [Triggers and cron](https://github.com/stephengpope/thepopebot/blob/main/lib/triggers.js): `lib/triggers.js`

### Platform services

- [Configuration resolver](https://github.com/stephengpope/thepopebot/blob/main/lib/config.js): `lib/config.js`
- [Settings storage](https://github.com/stephengpope/thepopebot/blob/main/lib/db/config.js): `lib/db/config.js`
- [SQLite database](https://github.com/stephengpope/thepopebot/blob/main/lib/db/index.js): `lib/db/index.js`
- [Data schema](https://github.com/stephengpope/thepopebot/blob/main/lib/db/schema.js): `lib/db/schema.js`

### Other components

- **Browser user**
- **Telegram user**
- **SQLite**
- **Docker service**
- **GitHub**
- **LLM provider**

## Connections

- Browser user → Web chat: uses
- Telegram user → Telegram adapter: messages
- Web chat → Chat actions: initiates
- Chat actions → AI runtime: calls (evidence: `lib/chat/actions.js`)
- Event handler API → AI runtime: calls (evidence: `api/index.js`)
- Event handler API → Agent jobs: creates (evidence: `api/index.js`)
- Event handler API → Telegram adapter: uses (evidence: `api/index.js`)
- Event handler API → Authentication: authenticates
- Telegram adapter → Event handler API: webhook
- AI runtime → Agent adapters: dispatches (evidence: `lib/ai/index.js`)
- AI runtime → Helper LLM: calls (evidence: `lib/ai/index.js`)
- AI runtime → Session persistence: reads/writes (evidence: `lib/ai/index.js`)
- AI runtime → Docker execution: gets workspace (evidence: `lib/ai/index.js`)
- AI runtime → LLM providers: uses configuration
- Code workspaces → Docker execution: manages workspace
- Agent jobs → Docker execution: launches container
- Agent jobs → GitHub integration: opens PR
- GitHub integration → GitHub: pushes and merges
- Event handler API → GitHub integration: fetches job logs (evidence: `api/index.js`)
- Cluster runtime → Docker execution: runs workers
- Triggers and cron → Agent jobs: schedules work
- Configuration resolver → Settings storage: reads settings (evidence: `lib/config.js`)
- Configuration resolver → LLM providers: resolves models (evidence: `lib/config.js`)
- Docker execution → Configuration resolver: reads settings (evidence: `lib/tools/docker.js`)
- Docker execution → Docker service: runs containers
- LLM providers → LLM provider: configures access
- SQLite database → SQLite: opens (evidence: `lib/db/index.js`)
- SQLite database → Data schema: uses schema (evidence: `lib/db/index.js`)
- Settings storage → SQLite database: queries (evidence: `lib/db/config.js`)
