# thrishok/telegram-agent architecture

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

- Interactive diagram: https://gitdiagram.com/thrishok/telegram-agent
- Repository: https://github.com/thrishok/telegram-agent

## Overview

Telegram-agent is a Telegram webhook assistant: incoming messages are routed to either a vision path for photos or a LangGraph tool-using chat path for text, then replies are sent back through Telegram. The text agent can invoke web search and a placeholder document-search tool; photo analysis uses a separate vision model. Webhook registration and health endpoints support operation. The implementation is concentrated in main.py; relationships shown here are evidenced by its excerpt.

Main entry points: [`main.py`](https://github.com/thrishok/telegram-agent/blob/main/main.py) (Webhook handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_webhook["Telegram Webhook"]
  node_webhook_handler["Webhook handler<br/>[main.py]"]
  node_reply_sender["Reply sender<br/>[main.py]"]
  node_webhook_admin["Webhook management<br/>[main.py]"]
end

subgraph group_chat["Text Agent"]
  node_agent_graph["LangGraph agent<br/>[main.py]"]
  node_tool_router["Tool router<br/>[main.py]"]
  node_web_search["Web search<br/>[main.py]"]
  node_document_search["Document search stub<br/>[main.py]"]
end

subgraph group_vision["Photo Analysis"]
  node_vision_analysis["Image analyzer<br/>[main.py]"]
end

subgraph group_integrations["External Services"]
  node_telegram_api["Telegram API"]
  node_groq_chat["Groq chat model"]
  node_tavily["Tavily search"]
end

node_telegram_user(("Telegram user"))

node_telegram_user -->|"sends update"| node_webhook_handler
node_webhook_handler -->|"invokes text agent"| node_agent_graph
node_agent_graph -->|"dispatches tools"| node_tool_router
node_tool_router -->|"returns tool result"| node_agent_graph
node_tool_router -->|"runs search"| node_web_search
node_tool_router -->|"runs search"| node_document_search
node_web_search -->|"queries"| node_tavily
node_agent_graph -->|"invokes model"| node_groq_chat
node_webhook_handler -->|"routes photos"| node_vision_analysis
node_vision_analysis -->|"invokes vision model"| node_groq_chat
node_webhook_handler -->|"downloads photo"| node_telegram_api
node_reply_sender -->|"sends reply"| node_telegram_api
node_webhook_handler -->|"passes response"| node_reply_sender
node_webhook_admin -->|"configures webhook"| node_telegram_api

click node_webhook_handler "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_reply_sender "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_webhook_admin "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_agent_graph "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_tool_router "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_web_search "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_document_search "https://github.com/thrishok/telegram-agent/blob/main/main.py"
click node_vision_analysis "https://github.com/thrishok/telegram-agent/blob/main/main.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_webhook_handler,node_reply_sender,node_webhook_admin,node_telegram_user toneBlue
class node_agent_graph,node_tool_router,node_web_search,node_document_search toneAmber
class node_vision_analysis toneMint
class node_telegram_api,node_groq_chat,node_tavily toneRose
```

## Components

### Telegram Webhook

- [Webhook handler](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`
- [Reply sender](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`
- [Webhook management](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`

### Text Agent

- [LangGraph agent](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`
- [Tool router](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`
- [Web search](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`
- [Document search stub](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`

### Photo Analysis

- [Image analyzer](https://github.com/thrishok/telegram-agent/blob/main/main.py): `main.py`

### External Services

- **Telegram API**
- **Groq chat model**
- **Tavily search**

### Other components

- **Telegram user**

## Connections

- Telegram user → Webhook handler: sends update (evidence: `main.py`)
- Webhook handler → LangGraph agent: invokes text agent (evidence: `main.py`)
- LangGraph agent → Tool router: dispatches tools (evidence: `main.py`)
- Tool router → LangGraph agent: returns tool result (evidence: `main.py`)
- Tool router → Web search: runs search (evidence: `main.py`)
- Tool router → Document search stub: runs search (evidence: `main.py`)
- Web search → Tavily search: queries (evidence: `main.py`)
- LangGraph agent → Groq chat model: invokes model (evidence: `main.py`)
- Webhook handler → Image analyzer: routes photos (evidence: `main.py`)
- Image analyzer → Groq chat model: invokes vision model (evidence: `main.py`)
- Webhook handler → Telegram API: downloads photo (evidence: `main.py`)
- Reply sender → Telegram API: sends reply (evidence: `main.py`)
- Webhook handler → Reply sender: passes response (evidence: `main.py`)
- Webhook management → Telegram API: configures webhook (evidence: `main.py`)