# richardatct/claude-code-telegram architecture

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

- Interactive diagram: https://gitdiagram.com/richardatct/claude-code-telegram
- Repository: https://github.com/richardatct/claude-code-telegram

## Overview

Claude Code Telegram Bot provides conversational and classic-mode access to project work, with per-user/project session continuity. Telegram updates enter the orchestrator and reach Claude for agentic responses; classic commands add project navigation and feature actions. A parallel automation path accepts webhooks and scheduled triggers through a typed event bus, with notifications delivering results. SQLite supports sessions, usage and automation state, while configuration and security checks constrain operation. The README documents feature breadth; unsampled modules and runtime wiring are represented only where tree/index or README evidence supports them.

Main entry points: [`src/bot/orchestrator.py`](https://github.com/richardatct/claude-code-telegram/blob/main/src/bot/orchestrator.py) (Update orchestrator), [`src/events/bus.py`](https://github.com/richardatct/claude-code-telegram/blob/main/src/events/bus.py) (Event bus), [`src/main.py`](https://github.com/richardatct/claude-code-telegram/blob/main/src/main.py) (Application startup), [`src/events/handlers.py`](https://github.com/richardatct/claude-code-telegram/blob/main/src/events/handlers.py) (Event handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Telegram interaction"]
  node_orchestrator["Update orchestrator<br/>[orchestrator.py]"]
  node_classic_handlers["Classic handlers"]
  node_feature_actions["Bot features"]
  node_project_threads["Project threads<br/>[thread_manager.py]"]
end

subgraph group_claude["Claude execution"]
  node_claude_facade["Claude facade<br/>[facade.py]"]
  node_claude_sdk["Claude SDK<br/>[sdk_integration.py]"]
  node_session_manager["Session manager<br/>[session.py]"]
  node_formatting["Response formatting<br/>[formatting.py]"]
end

subgraph group_automation["Event automation"]
  node_webhook_api["Webhook API<br/>[server.py]"]
  node_scheduler["Job scheduler<br/>[scheduler.py]"]
  node_event_bus["Event bus<br/>[bus.py]"]
  node_event_handlers["Event handlers<br/>[handlers.py]"]
  node_notifications["Notifications<br/>[service.py]"]
end

subgraph group_platform["Security and configuration"]
  node_settings["Settings<br/>[settings.py]"]
  node_security["Security controls"]
  node_application["Application startup<br/>[main.py]"]
end

subgraph group_persistence["Persistence"]
  node_storage[("SQLite storage<br/>[database.py]")]
  node_repositories["Data repositories<br/>[repositories.py]"]
  node_session_storage["Session persistence<br/>[session_storage.py]"]
end

node_telegram_user(("Telegram user"))
node_external_trigger(("Webhook or schedule"))

node_telegram_user -->|"sends updates"| node_orchestrator
node_orchestrator -->|"routes classic mode"| node_classic_handlers
node_orchestrator -->|"runs agentic requests"| node_claude_sdk
node_orchestrator -->|"syncs topics"| node_project_threads
node_classic_handlers -.->|"offers actions"| node_feature_actions
node_claude_facade -->|"delegates execution"| node_claude_sdk
node_claude_facade -->|"manages sessions"| node_session_manager
node_orchestrator -->|"formats replies"| node_formatting
node_external_trigger -->|"sends webhook"| node_webhook_api
node_webhook_api -->|"publishes events"| node_event_bus
node_scheduler -->|"publishes triggers"| node_event_bus
node_event_bus -->|"dispatches events"| node_event_handlers
node_event_handlers -->|"requests agent work"| node_claude_facade
node_event_handlers -.->|"routes responses"| node_notifications
node_notifications -.->|"delivers results"| node_telegram_user
node_application -->|"loads configuration"| node_settings
node_application -->|"starts runtime bus"| node_event_bus
node_application -.->|"configures jobs"| node_scheduler
node_claude_sdk -->|"validates tool paths"| node_security
node_session_manager -.->|"persists sessions"| node_session_storage
node_session_storage -->|"uses database connections"| node_storage
node_repositories -->|"uses database connections"| node_storage
node_project_threads -->|"reads thread mappings"| node_repositories

click node_orchestrator "https://github.com/richardatct/claude-code-telegram/blob/main/src/bot/orchestrator.py"
click node_classic_handlers "https://github.com/richardatct/claude-code-telegram/tree/main/src/bot/handlers"
click node_feature_actions "https://github.com/richardatct/claude-code-telegram/tree/main/src/bot/features"
click node_project_threads "https://github.com/richardatct/claude-code-telegram/blob/main/src/projects/thread_manager.py"
click node_claude_facade "https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/facade.py"
click node_claude_sdk "https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/sdk_integration.py"
click node_session_manager "https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/session.py"
click node_formatting "https://github.com/richardatct/claude-code-telegram/blob/main/src/bot/utils/formatting.py"
click node_webhook_api "https://github.com/richardatct/claude-code-telegram/blob/main/src/api/server.py"
click node_scheduler "https://github.com/richardatct/claude-code-telegram/blob/main/src/scheduler/scheduler.py"
click node_event_bus "https://github.com/richardatct/claude-code-telegram/blob/main/src/events/bus.py"
click node_event_handlers "https://github.com/richardatct/claude-code-telegram/blob/main/src/events/handlers.py"
click node_notifications "https://github.com/richardatct/claude-code-telegram/blob/main/src/notifications/service.py"
click node_settings "https://github.com/richardatct/claude-code-telegram/blob/main/src/config/settings.py"
click node_security "https://github.com/richardatct/claude-code-telegram/tree/main/src/security"
click node_application "https://github.com/richardatct/claude-code-telegram/blob/main/src/main.py"
click node_storage "https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/database.py"
click node_repositories "https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/repositories.py"
click node_session_storage "https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/session_storage.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_orchestrator,node_classic_handlers,node_feature_actions,node_project_threads,node_telegram_user toneBlue
class node_claude_facade,node_claude_sdk,node_session_manager,node_formatting toneAmber
class node_webhook_api,node_scheduler,node_event_bus,node_event_handlers,node_notifications,node_external_trigger toneMint
class node_settings,node_security,node_application toneRose
class node_storage,node_repositories,node_session_storage toneIndigo
```

## Components

### Telegram interaction

- [Update orchestrator](https://github.com/richardatct/claude-code-telegram/blob/main/src/bot/orchestrator.py): `src/bot/orchestrator.py`
- [Classic handlers](https://github.com/richardatct/claude-code-telegram/tree/main/src/bot/handlers): `src/bot/handlers`
- [Bot features](https://github.com/richardatct/claude-code-telegram/tree/main/src/bot/features): `src/bot/features`
- [Project threads](https://github.com/richardatct/claude-code-telegram/blob/main/src/projects/thread_manager.py): `src/projects/thread_manager.py`

### Claude execution

- [Claude facade](https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/facade.py): `src/claude/facade.py`
- [Claude SDK](https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/sdk_integration.py): `src/claude/sdk_integration.py`
- [Session manager](https://github.com/richardatct/claude-code-telegram/blob/main/src/claude/session.py): `src/claude/session.py`
- [Response formatting](https://github.com/richardatct/claude-code-telegram/blob/main/src/bot/utils/formatting.py): `src/bot/utils/formatting.py`

### Event automation

- [Webhook API](https://github.com/richardatct/claude-code-telegram/blob/main/src/api/server.py): `src/api/server.py`
- [Job scheduler](https://github.com/richardatct/claude-code-telegram/blob/main/src/scheduler/scheduler.py): `src/scheduler/scheduler.py`
- [Event bus](https://github.com/richardatct/claude-code-telegram/blob/main/src/events/bus.py): `src/events/bus.py`
- [Event handlers](https://github.com/richardatct/claude-code-telegram/blob/main/src/events/handlers.py): `src/events/handlers.py`
- [Notifications](https://github.com/richardatct/claude-code-telegram/blob/main/src/notifications/service.py): `src/notifications/service.py`

### Security and configuration

- [Settings](https://github.com/richardatct/claude-code-telegram/blob/main/src/config/settings.py): `src/config/settings.py`
- [Security controls](https://github.com/richardatct/claude-code-telegram/tree/main/src/security): `src/security`
- [Application startup](https://github.com/richardatct/claude-code-telegram/blob/main/src/main.py): `src/main.py`

### Persistence

- [SQLite storage](https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/database.py): `src/storage/database.py`
- [Data repositories](https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/repositories.py): `src/storage/repositories.py`
- [Session persistence](https://github.com/richardatct/claude-code-telegram/blob/main/src/storage/session_storage.py): `src/storage/session_storage.py`

### Other components

- **Telegram user**
- **Webhook or schedule**

## Connections

- Telegram user → Update orchestrator: sends updates (evidence: `README.md`)
- Update orchestrator → Classic handlers: routes classic mode (evidence: `src/bot/orchestrator.py`)
- Update orchestrator → Claude SDK: runs agentic requests (evidence: `src/bot/orchestrator.py`)
- Update orchestrator → Project threads: syncs topics (evidence: `src/bot/orchestrator.py`)
- Classic handlers → Bot features: offers actions (evidence: `README.md`)
- Claude facade → Claude SDK: delegates execution (evidence: `src/claude/facade.py`)
- Claude facade → Session manager: manages sessions (evidence: `src/claude/facade.py`)
- Update orchestrator → Response formatting: formats replies (evidence: `src/bot/orchestrator.py`)
- Webhook or schedule → Webhook API: sends webhook (evidence: `README.md`)
- Webhook API → Event bus: publishes events (evidence: `src/api/server.py`)
- Job scheduler → Event bus: publishes triggers (evidence: `src/scheduler/scheduler.py`)
- Event bus → Event handlers: dispatches events (evidence: `src/events/bus.py`)
- Event handlers → Claude facade: requests agent work (evidence: `src/events/handlers.py`)
- Event handlers → Notifications: routes responses
- Notifications → Telegram user: delivers results (evidence: `README.md`)
- Application startup → Settings: loads configuration (evidence: `src/main.py`)
- Application startup → Event bus: starts runtime bus (evidence: `src/main.py`)
- Application startup → Job scheduler: configures jobs (evidence: `README.md`)
- Claude SDK → Security controls: validates tool paths (evidence: `src/claude/sdk_integration.py`)
- Session manager → Session persistence: persists sessions (evidence: `src/claude/session.py`)
- Session persistence → SQLite storage: uses database connections (evidence: `src/storage/session_storage.py`)
- Data repositories → SQLite storage: uses database connections (evidence: `src/storage/repositories.py`)
- Project threads → Data repositories: reads thread mappings (evidence: `src/projects/thread_manager.py`)