# kargarisaac/telegram_link_summarizer_agent architecture

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

- Interactive diagram: https://gitdiagram.com/kargarisaac/telegram_link_summarizer_agent
- Repository: https://github.com/kargarisaac/telegram_link_summarizer_agent

## Overview

1. **Project shape**
   - This is a **stateless Telegram bot service** whose main job is to ingest a chat message containing a link, analyze the link type, fetch the underlying content, and return a concise summary.
   - The runtime is centered around a Python service entrypoint, with the core workflow implemented as an **agentic graph** rather than a simple request-handler pipeline.

2. **Primary entrypoints**
   - `bot.py` is the production entrypoint for the Telegram bot. It likely owns webhook/polling startup, Telegram update handling, health endpoint exposure, and dispatch into the agent workflow.
   - `agent.py` appears to be the main local/test harness for running the summarization agent directly against sample URLs without Telegram.
   - `agent_viz.py` is a utility entrypoint for generating a visual representation of the LangGraph workflow.

3. **Orchestration layer**
   - The main control plane is **LangGraph**, which coordinates multi-step reasoning and tool use.
   - The graph likely follows a pattern of: receive URL/message → route request type → invoke the right extractor/tool → normalize content → summarize → return response.
   - This is the architectural boundary between Telegram I/O and the domain logic; the bot entrypoint should be thin, with the graph doing the real work.

4. **LLM and structured output boundary**
   - `baml_src/` contains BAML definitions such as `router.baml`, `summarize.baml`, `clients.baml`, and `generators.baml`.
   - `baml_client/` is the generated Python client/runtime used by the application to call those BAML-defined functions.
   - The important architectural role of BAML here is to provide **structured routing and summarization outputs** from LLMs, especially for:
     - classifying the link type,
     - producing consistent summary objects/text,
     - isolating model/provider details from the rest of the app.

5. **Content-type routing subsystem**
   - The repository explicitly supports multiple link categories: **web pages, PDFs, Twitter/X, LinkedIn, YouTube, and unsupported URLs**.
   - Routing is handled by an LLM-based decision step (`RouteRequest` per the README) rather than hard-coded URL pattern matching alone.
   - This router is a key architectural boundary because it determines which downstream tool chain will be used and prevents every URL from going through the same extractor.

6. **Specialized extraction tools**
   - The `tools/` package contains the domain-specific fetch/extraction adapters:
     - `search.py` for general web search/content retrieval, likely backed by Tavily.
     - `pdf_handler.py` for extracting text from PDF URLs using PyMuPDF.
     - `twitter_api_tool.py` for pulling tweet/thread content via `twitterapi.io`.
     - `linkedin_agentql_scraper.py` and `youtube_agentql_scraper.py` for browser-based extraction with Playwright + AgentQL.
   - These tools form the **integration layer** between the agent and external content sources.

7. **External service dependencies**
   - **Telegram Bot API** is the user-facing ingress/egress channel.
   - **Tavily** is used for generic web extraction/search.
   - **twitterapi.io** provides Twitter/X content access.
   - **AgentQL + Playwright** handle sites that need browser automation, especially YouTube and LinkedIn.
   - **LLM providers** such as Gemini or DeepSeek are used through BAML for routing and summarization.
   - These services matter architecturally because the bot is a composition of several external APIs, not a monolithic local NLP pipeline.

8. **Delivery/runtime model**
   - The app is designed to run in **two modes**:
     - **Polling mode** for simpler self-hosted setups.
     - **Webhook mode** behind a public URL for production or Cloud Run.
   - The README and scripts indicate a **FastAPI + Uvicorn** server is used for webhook delivery and health checks.
   - This means the bot has a server boundary, but the core summarization logic remains independent from the transport mode.

9. **Deployment boundaries**
   - The repository is built for containerized deployment via **Docker**.
   - `scripts/run_local.sh`, `scripts/run_docker.sh`, `scripts/deploy_server.sh`, and `scripts/deploy_cloud_run.sh` represent distinct deployment paths:
     - local development,
     - local container testing,
     - self-managed server/VM,
     - Google Cloud Run.
   - Cloud Run deployment is integrated with Google Secret Manager and Artifact Registry, which matters because secrets are not hardcoded into the app runtime.

10. **Configuration and secrets**
   - The system is strongly environment-driven: Telegram token, webhook settings, LLM key, Tavily key, Twitter API key, AgentQL key, and possibly webhook secrets are all injected via env vars.
   - This makes the application effectively **12-factor** and helps keep the bot stateless and portable across environments.
   - The deployment scripts are part of the architecture because they enforce how secrets and webhook URLs are wired into the running service.

11. **Runtime flow from message to response**
   - A Telegram message enters `bot.py`.
   - The message text is parsed to identify a URL.
   - The agent graph routes the URL to the appropriate extractor.
   - The extractor returns raw or semi-structured content.
   - BAML/LLM summarization turns that content into a concise response.
   - The bot sends the summary back to Telegram, typically with silent failure behavior on unsupported/invalid links.

12. **Observability and debugging**
   - The project includes `agent_viz.py` and an image-based system diagram in `images/`, suggesting the graph is important enough to be visualized and reasoned about independently.
   - There is also a `/health` endpoint used by the deployment scripts, so health checking is part of the operational surface.
   - No persistent datastore is visible in the repository, so debugging and state inspection likely rely on logs and graph visualization rather than stored records.

13. **What is not present**
   - There is no obvious database, queue, or background job worker in the tree.
   - That implies each message is processed synchronously within the request/update lifecycle, with all state kept in-memory during a single execution path.
   - This keeps the architecture simple: ingress → agent graph → external tools/LLM → Telegram response.

14. **How to draw it**
   - Draw `bot.py` as the transport layer at the edge.
   - Behind it, draw a central LangGraph orchestration box.
   - From that box, branch to the specialized tool adapters in `tools/`.
   - Put BAML/BAML client as the structured LLM layer used by the graph.
   - Show external services on the far side: Telegram, Tavily, Twitter API, AgentQL/Playwright, and LLM providers.
   - Add deployment/runtime boxes for Docker, FastAPI/Uvicorn, and Cloud Run only as operational wrappers around the same core agent.

Main entry points: [`baml_src/router.baml`](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/router.baml) (Route request), [`scripts/run_local.sh`](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/scripts/run_local.sh) (Deploy scripts), [`bot.py`](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/bot.py) (Telegram bot), [`baml_src/summarize.baml`](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/summarize.baml) (Summarize)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Runtime"]
  node_n1["Telegram bot<br/>entrypoint<br/>[bot.py]"]
  node_n2["Agent harness<br/>entrypoint<br/>[agent.py]"]
  node_n3["Graph viz<br/>[agent_viz.py]"]
end

subgraph group_g2["Orchestration"]
  node_n4{{"LangGraph flow<br/>orchestrator"}}
  node_n5["Route request<br/>router<br/>[router.baml]"]
  node_n6["Summarize<br/>llm task<br/>[summarize.baml]"]
  node_n7["BAML client<br/>runtime client<br/>[__init__.py]"]
  node_n8["Client config<br/>client runtime<br/>[config.py]"]
end

subgraph group_g3["Extractors"]
  node_n9["Web fetch<br/>web extractor<br/>[search.py]"]
  node_n10["PDF extract<br/>[pdf_handler.py]"]
  node_n11["Twitter fetch<br/>social extractor"]
  node_n12["LinkedIn scrape<br/>browser scraper"]
  node_n13["YouTube scrape<br/>browser scraper"]
end

subgraph group_g4["Ops"]
  node_n14[("Telegram API<br/>external service")]
  node_n15[("LLM provider<br/>external model api")]
  node_n16[("Tavily<br/>external search api")]
  node_n17[("twitterapi.io<br/>external social api")]
  node_n18[("AgentQL/Playwright<br/>external browser stack")]
  node_n19["Webhook server<br/>runtime server"]
  node_n20["Deploy scripts<br/>ops scripts<br/>[run_local.sh]"]
end

node_n1 -->|"dispatch"| node_n4
node_n2 -->|"invoke"| node_n4
node_n3 -.->|"render"| node_n4
node_n4 -->|"route"| node_n5
node_n4 -->|"summarize"| node_n6
node_n4 -->|"call"| node_n7
node_n7 -.->|"configure"| node_n8
node_n5 -->|"web"| node_n9
node_n5 -->|"pdf"| node_n10
node_n5 -->|"twitter"| node_n11
node_n5 -->|"linkedin"| node_n12
node_n5 -->|"youtube"| node_n13
node_n9 -->|"search"| node_n16
node_n11 -->|"fetch"| node_n17
node_n12 -->|"browser"| node_n18
node_n13 -->|"browser"| node_n18
node_n6 -->|"llm"| node_n15
node_n5 -->|"classify"| node_n15
node_n1 -.->|"webhook"| node_n19
node_n20 -.->|"start"| node_n19
node_n20 -.->|"run"| node_n1
node_n20 -.->|"wire"| node_n4

click node_n1 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/bot.py"
click node_n2 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/agent.py"
click node_n3 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/agent_viz.py"
click node_n5 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/router.baml"
click node_n6 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/summarize.baml"
click node_n7 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_client/__init__.py"
click node_n8 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_client/config.py"
click node_n9 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/search.py"
click node_n10 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/pdf_handler.py"
click node_n11 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/twitter_api_tool.py"
click node_n12 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/linkedin_agentql_scraper.py"
click node_n13 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/youtube_agentql_scraper.py"
click node_n20 "https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/scripts/run_local.sh"

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_n1,node_n2,node_n3 toneBlue
class node_n4,node_n5,node_n6,node_n7,node_n8 toneAmber
class node_n9,node_n10,node_n11,node_n12,node_n13 toneMint
class node_n14,node_n15,node_n16,node_n17,node_n18,node_n19,node_n20 toneRose
```

## Components

### Runtime

Service entrypoints and execution modes

- [Telegram bot](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/bot.py): entrypoint · Production bot entrypoint for receiving updates and sending replies · `bot.py`
- [Agent harness](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/agent.py): entrypoint · Local/test runner for invoking the summarization agent directly · `agent.py`
- [Graph viz](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/agent_viz.py): utility · Generates a visual representation of the LangGraph workflow · `agent_viz.py`

### Orchestration

Agent graph and structured LLM boundary

- **LangGraph flow**: orchestrator · Central multi-step request routing, extraction, and summarization graph
- [Route request](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/router.baml): router · Classifies link type and chooses the downstream extraction path · `baml_src/router.baml`
- [Summarize](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_src/summarize.baml): llm task · Produces concise summary output from extracted content · `baml_src/summarize.baml`
- [BAML client](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_client/__init__.py): runtime client · Generated Python client used to invoke BAML-defined functions · `baml_client/__init__.py`
- [Client config](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/baml_client/config.py): client runtime · BAML client configuration and request plumbing · `baml_client/config.py`

### Extractors

Specialized content adapters for different link types

- [Web fetch](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/search.py): web extractor · General web search and content retrieval adapter · `tools/search.py`
- [PDF extract](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/pdf_handler.py): pdf extractor · Extracts text from PDF URLs · `tools/pdf_handler.py`
- [Twitter fetch](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/twitter_api_tool.py): social extractor · Fetches tweet or thread content from Twitter/X · `tools/twitter_api_tool.py`
- [LinkedIn scrape](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/linkedin_agentql_scraper.py): browser scraper · Browser-based LinkedIn content extraction · `tools/linkedin_agentql_scraper.py`
- [YouTube scrape](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/tools/youtube_agentql_scraper.py): browser scraper · Browser-based YouTube content extraction · `tools/youtube_agentql_scraper.py`

### Ops

Deployment, health, and packaging

- **Telegram API**: external service · User ingress and reply channel
- **LLM provider**: external model api · Model backend used for routing and summarization through BAML
- **Tavily**: external search api · External search and retrieval dependency for generic web content
- **twitterapi.io**: external social api · External API used to retrieve Twitter/X content
- **AgentQL/Playwright**: external browser stack · Automation stack for LinkedIn and YouTube scraping
- **Webhook server**: runtime server · FastAPI/Uvicorn delivery path for webhook mode and health checks
- [Deploy scripts](https://github.com/kargarisaac/telegram_link_summarizer_agent/blob/main/scripts/run_local.sh): ops scripts · Local, server, Docker, and Cloud Run deployment entry scripts · `scripts/run_local.sh`

## Connections

- Telegram bot → LangGraph flow: dispatch · Telegram updates are handed off to the agent graph
- Agent harness → LangGraph flow: invoke · Local harness runs the same core workflow
- Graph viz → LangGraph flow: render · Visualization targets the agent graph structure
- LangGraph flow → Route request: route · Graph first classifies the incoming link
- LangGraph flow → Summarize: summarize · Graph produces the final concise summary
- LangGraph flow → BAML client: call · Graph uses the generated BAML client for model calls
- BAML client → Client config: configure · Client runtime is driven by its config layer
- Route request → Web fetch: web · Generic URLs are handled via search/content retrieval
- Route request → PDF extract: pdf · PDF links are extracted with the PDF handler
- Route request → Twitter fetch: twitter · Twitter/X links are fetched through the social API tool
- Route request → LinkedIn scrape: linkedin · LinkedIn links are scraped through browser automation
- Route request → YouTube scrape: youtube · YouTube links are scraped through browser automation
- Web fetch → Tavily: search · Web retrieval depends on Tavily
- Twitter fetch → twitterapi.io: fetch · Twitter tool depends on twitterapi.io
- LinkedIn scrape → AgentQL/Playwright: browser · LinkedIn scraper depends on AgentQL and Playwright
- YouTube scrape → AgentQL/Playwright: browser · YouTube scraper depends on AgentQL and Playwright
- Summarize → LLM provider: llm · Summarization is delegated to the model provider
- Route request → LLM provider: classify · Routing uses LLM-backed structured output
- Telegram bot → Webhook server: webhook · Production delivery can run behind the webhook server
- Deploy scripts → Webhook server: start · Deployment scripts launch the server runtime
- Deploy scripts → Telegram bot: run · Deployment paths ultimately run the bot service
- Deploy scripts → LangGraph flow: wire · Deployment exposes the core agent workflow
