# imluckyluke/opencode-telegram-bot architecture

> Architecture diagram of the GitHub repository imluckyluke/opencode-telegram-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imluckyluke/opencode-telegram-bot
- Repository: https://github.com/imluckyluke/opencode-telegram-bot

## Overview

OpenCode Telegram Bot lets users run and monitor local OpenCode coding sessions through Telegram. The main flow is a Telegram prompt entering the bot, being sent to OpenCode with the selected session and model, and returning as streamed or formatted output. Separate documented capabilities cover session and project controls, scheduled work, attachments and voice, guest interactions, and live status. The graph preserves those product branches; links for unsampled subsystems rely on README descriptions, so their internal call paths are not asserted.

Main entry points: [`src/bot/handlers/prompt.ts`](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/handlers/prompt.ts) (Prompt handling), [`src/bot/services/event-subscription-service.ts`](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/services/event-subscription-service.ts) (Live event handling), [`src/opencode/client.ts`](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/opencode/client.ts) (OpenCode client), [`src/app/services/session-service.ts`](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/session-service.ts) (Session service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interaction"]
  node_bot_entry["Bot application<br/>[index.ts]"]
  node_routers["Message routers"]
  node_prompt_handler["Prompt handling<br/>[prompt.ts]"]
  node_response["Response rendering"]
  node_render_pipeline["Telegram formatting<br/>[pipeline.ts]"]
end

subgraph group_sessions["Sessions and controls"]
  node_session_service["Session service<br/>[session-service.ts]"]
  node_model_selection["Model selection"]
  node_agent_selection["Agent selection"]
  node_event_subscriptions["Live event handling"]
  node_summaries["Run summaries"]
  node_pinned_status["Pinned status"]
end

subgraph group_runtime["OpenCode runtime"]
  node_opencode_client["OpenCode client<br/>[client.ts]"]
  node_opencode_server{{"Local OpenCode"}}
end

subgraph group_capabilities["Additional capabilities"]
  node_scheduled_tasks["Scheduled tasks"]
  node_attachments["File attachments<br/>[attach-service.ts]"]
  node_voice["Voice prompts<br/>[voice-handler.ts]"]
  node_file_browser["Project file browser"]
  node_guest_mode["Guest interactions<br/>[inline-router.ts]"]
end

subgraph group_state["Configuration and state"]
  node_session_state[("Session state<br/>[settings-store.ts]")]
  node_settings[("Runtime settings<br/>[settings-store.ts]")]
  node_localization["Localization<br/>[index.ts]"]
end

node_user(("Telegram user"))

node_user -->|"sends requests"| node_bot_entry
node_bot_entry -->|"routes updates"| node_routers
node_routers -.->|"dispatches prompts"| node_prompt_handler
node_prompt_handler -->|"uses session"| node_session_service
node_session_service -->|"reads and updates"| node_session_state
node_prompt_handler -.->|"submits coding tasks"| node_opencode_client
node_opencode_client -->|"calls local API"| node_opencode_server
node_prompt_handler -.->|"delivers results"| node_response
node_response -->|"formats output"| node_render_pipeline
node_opencode_client -.->|"provides session events"| node_event_subscriptions
node_event_subscriptions -->|"aggregates run activity"| node_summaries
node_event_subscriptions -->|"updates live status"| node_pinned_status
node_user -.->|"manages sessions"| node_session_service
node_user -.->|"switches models"| node_model_selection
node_user -.->|"switches agents"| node_agent_selection
node_user -.->|"schedules prompts"| node_scheduled_tasks
node_user -.->|"attaches files"| node_attachments
node_user -.->|"sends voice prompts"| node_voice
node_user -.->|"browses project files"| node_file_browser
node_user -.->|"starts guest runs"| node_guest_mode
node_user -.->|"changes preferences"| node_settings
node_settings -->|"selects locale"| node_localization

click node_bot_entry "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/index.ts"
click node_routers "https://github.com/imluckyluke/opencode-telegram-bot/tree/main/src/bot/routers"
click node_prompt_handler "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/handlers/prompt.ts"
click node_response "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/messages/assistant-rendering.ts"
click node_render_pipeline "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/render/pipeline.ts"
click node_session_service "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/session-service.ts"
click node_session_state "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/stores/settings-store.ts"
click node_model_selection "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/model-selection-service.ts"
click node_agent_selection "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/agent-selection-service.ts"
click node_event_subscriptions "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/services/event-subscription-service.ts"
click node_summaries "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/managers/summary-aggregation-manager.ts"
click node_pinned_status "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/pinned/pinned-message-manager.ts"
click node_opencode_client "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/opencode/client.ts"
click node_scheduled_tasks "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/scheduled-task-executor-service.ts"
click node_attachments "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/attach-service.ts"
click node_voice "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/handlers/voice-handler.ts"
click node_file_browser "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/file-browser-service.ts"
click node_guest_mode "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/routers/inline-router.ts"
click node_settings "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/stores/settings-store.ts"
click node_localization "https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/i18n/index.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_bot_entry,node_routers,node_prompt_handler,node_response,node_render_pipeline,node_user toneBlue
class node_session_service,node_model_selection,node_agent_selection,node_event_subscriptions,node_summaries,node_pinned_status toneAmber
class node_opencode_client,node_opencode_server toneMint
class node_scheduled_tasks,node_attachments,node_voice,node_file_browser,node_guest_mode toneRose
class node_session_state,node_settings,node_localization toneIndigo
```

## Components

### Telegram interaction

- [Bot application](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/index.ts): `src/bot/index.ts`
- [Message routers](https://github.com/imluckyluke/opencode-telegram-bot/tree/main/src/bot/routers): `src/bot/routers`
- [Prompt handling](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/handlers/prompt.ts): `src/bot/handlers/prompt.ts`
- [Response rendering](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/messages/assistant-rendering.ts): `src/bot/messages/assistant-rendering.ts`
- [Telegram formatting](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/render/pipeline.ts): `src/bot/render/pipeline.ts`

### Sessions and controls

- [Session service](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/session-service.ts): `src/app/services/session-service.ts`
- [Model selection](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/model-selection-service.ts): `src/app/services/model-selection-service.ts`
- [Agent selection](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/agent-selection-service.ts): `src/app/services/agent-selection-service.ts`
- [Live event handling](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/services/event-subscription-service.ts): `src/bot/services/event-subscription-service.ts`
- [Run summaries](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/managers/summary-aggregation-manager.ts): `src/app/managers/summary-aggregation-manager.ts`
- [Pinned status](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/pinned/pinned-message-manager.ts): `src/bot/pinned/pinned-message-manager.ts`

### OpenCode runtime

- [OpenCode client](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/opencode/client.ts): `src/opencode/client.ts`
- **Local OpenCode**

### Additional capabilities

- [Scheduled tasks](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/scheduled-task-executor-service.ts): `src/app/services/scheduled-task-executor-service.ts`
- [File attachments](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/attach-service.ts): `src/app/services/attach-service.ts`
- [Voice prompts](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/handlers/voice-handler.ts): `src/bot/handlers/voice-handler.ts`
- [Project file browser](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/services/file-browser-service.ts): `src/app/services/file-browser-service.ts`
- [Guest interactions](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/bot/routers/inline-router.ts): `src/bot/routers/inline-router.ts`

### Configuration and state

- [Session state](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/stores/settings-store.ts): `src/app/stores/settings-store.ts`
- [Runtime settings](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/app/stores/settings-store.ts): `src/app/stores/settings-store.ts`
- [Localization](https://github.com/imluckyluke/opencode-telegram-bot/blob/main/src/i18n/index.ts): `src/i18n/index.ts`

### Other components

- **Telegram user**

## Connections

- Telegram user → Bot application: sends requests (evidence: `README.md`)
- Bot application → Message routers: routes updates (evidence: `src/bot/index.ts`)
- Message routers → Prompt handling: dispatches prompts (evidence: `src/bot/routers/inline-router.ts`)
- Prompt handling → Session service: uses session (evidence: `src/app/services/session-service.ts`)
- Session service → Session state: reads and updates (evidence: `src/app/services/session-service.ts`)
- Prompt handling → OpenCode client: submits coding tasks (evidence: `README.md`)
- OpenCode client → Local OpenCode: calls local API (evidence: `README.md`)
- Prompt handling → Response rendering: delivers results (evidence: `README.md`)
- Response rendering → Telegram formatting: formats output (evidence: `src/bot/messages/assistant-rendering.ts`)
- OpenCode client → Live event handling: provides session events (evidence: `README.md`)
- Live event handling → Run summaries: aggregates run activity (evidence: `src/bot/services/event-subscription-service.ts`)
- Live event handling → Pinned status: updates live status (evidence: `src/bot/services/event-subscription-service.ts`)
- Telegram user → Session service: manages sessions (evidence: `README.md`)
- Telegram user → Model selection: switches models (evidence: `README.md`)
- Telegram user → Agent selection: switches agents (evidence: `README.md`)
- Telegram user → Scheduled tasks: schedules prompts (evidence: `README.md`)
- Telegram user → File attachments: attaches files (evidence: `README.md`)
- Telegram user → Voice prompts: sends voice prompts (evidence: `README.md`)
- Telegram user → Project file browser: browses project files (evidence: `README.md`)
- Telegram user → Guest interactions: starts guest runs (evidence: `README.md`)
- Telegram user → Runtime settings: changes preferences (evidence: `README.md`)
- Runtime settings → Localization: selects locale (evidence: `src/app/stores/settings-store.ts`)
