# armen-devops/telegram_bot architecture

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

- Interactive diagram: https://gitdiagram.com/armen-devops/telegram_bot
- Repository: https://github.com/armen-devops/telegram_bot

## Overview

Telegram Rate Bot serves current AMD exchange rates and guided currency conversions. A user interacts with Telegram commands or inline buttons; `tbot.py` formats responses and, when rates are needed, reads the scraper’s in-memory cache. `scraper.py` refreshes that cache from rate.am in a background thread, retrying after failures. The converter tracks a short-lived chat state and converts through AMD using buy and sell rates. The graph reflects documented capabilities and relationships visible in the excerpts; README-documented details are included where implementation is not separated into its own source file.

Main entry points: [`tbot.py`](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py) (Bot runtime), [`scraper.py`](https://github.com/armen-devops/telegram_bot/blob/main/scraper.py) (Refresh lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram Bot"]
  node_bot_runtime["Bot runtime<br/>[tbot.py]"]
  node_start_help["Welcome and help<br/>[tbot.py]"]
  node_rates_reply["Rates replies<br/>[tbot.py]"]
  node_currency_buttons["Currency buttons<br/>[tbot.py]"]
  node_clear_chat["Chat clearing<br/>[tbot.py]"]
  node_response_format["Rate and time formatting<br/>[tbot.py]"]
end

subgraph group_conversion["Conversion"]
  node_converter_flow["Converter prompts<br/>[tbot.py]"]
  node_convert_state[("Chat flow state<br/>[tbot.py]")]
  node_amount_parser["Amount parsing<br/>[tbot.py]"]
  node_amd_conversion["AMD conversion<br/>[tbot.py]"]
end

subgraph group_rates["Rate Collection"]
  node_scraper_runtime["Refresh lifecycle<br/>[scraper.py]"]
  node_scrape_extract["Browser scrape<br/>[scraper.py]"]
  node_rate_cache[("In-memory rates<br/>[scraper.py]")]
end

node_user(("Telegram user"))
node_telegram["Telegram API"]
node_rate_am["rate.am"]
node_chrome["Headless Chrome"]

node_user -->|"sends commands"| node_telegram
node_telegram -->|"delivers updates"| node_bot_runtime
node_bot_runtime -->|"polls and replies"| node_telegram
node_bot_runtime -->|"dispatches commands"| node_start_help
node_bot_runtime -->|"dispatches commands"| node_rates_reply
node_bot_runtime -->|"dispatches commands"| node_converter_flow
node_bot_runtime -->|"dispatches commands"| node_clear_chat
node_start_help -->|"sends welcome and help"| node_telegram
node_start_help -->|"includes buttons"| node_currency_buttons
node_currency_buttons -->|"requests currency rate"| node_rates_reply
node_rates_reply -->|"reads rows and timestamp"| node_rate_cache
node_rates_reply -->|"formats rate response"| node_response_format
node_response_format -->|"sends formatted reply"| node_telegram
node_converter_flow -->|"updates flow state"| node_convert_state
node_converter_flow -->|"parses entered amount"| node_amount_parser
node_converter_flow -->|"reads conversion rates"| node_rate_cache
node_converter_flow -->|"converts amount"| node_amd_conversion
node_amd_conversion -->|"provides result"| node_response_format
node_converter_flow -->|"prompts and sends result"| node_telegram
node_clear_chat -->|"resets unfinished flow"| node_convert_state
node_clear_chat -->|"deletes messages"| node_telegram
node_bot_runtime -->|"starts and closes"| node_scraper_runtime
node_scraper_runtime -->|"runs refresh scrape"| node_scrape_extract
node_scrape_extract -->|"loads and reads page"| node_chrome
node_scrape_extract -->|"fetches rate rows"| node_rate_am
node_scraper_runtime -->|"stores refreshed rows"| node_rate_cache

click node_bot_runtime "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_start_help "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_rates_reply "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_currency_buttons "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_clear_chat "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_converter_flow "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_convert_state "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_amount_parser "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_amd_conversion "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_response_format "https://github.com/armen-devops/telegram_bot/blob/main/tbot.py"
click node_scraper_runtime "https://github.com/armen-devops/telegram_bot/blob/main/scraper.py"
click node_scrape_extract "https://github.com/armen-devops/telegram_bot/blob/main/scraper.py"
click node_rate_cache "https://github.com/armen-devops/telegram_bot/blob/main/scraper.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_bot_runtime,node_start_help,node_rates_reply,node_currency_buttons,node_clear_chat,node_response_format,node_user toneBlue
class node_converter_flow,node_convert_state,node_amount_parser,node_amd_conversion toneAmber
class node_scraper_runtime,node_scrape_extract,node_rate_cache,node_telegram toneMint
class node_rate_am,node_chrome toneIndigo
```

## Components

### Telegram Bot

- [Bot runtime](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Welcome and help](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Rates replies](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Currency buttons](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Chat clearing](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Rate and time formatting](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`

### Conversion

- [Converter prompts](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Chat flow state](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [Amount parsing](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`
- [AMD conversion](https://github.com/armen-devops/telegram_bot/blob/main/tbot.py): `tbot.py`

### Rate Collection

- [Refresh lifecycle](https://github.com/armen-devops/telegram_bot/blob/main/scraper.py): `scraper.py`
- [Browser scrape](https://github.com/armen-devops/telegram_bot/blob/main/scraper.py): `scraper.py`
- [In-memory rates](https://github.com/armen-devops/telegram_bot/blob/main/scraper.py): `scraper.py`

### Other components

- **Telegram user**
- **Telegram API**
- **rate.am**
- **Headless Chrome**

## Connections

- Telegram user → Telegram API: sends commands (evidence: `README.md`)
- Telegram API → Bot runtime: delivers updates (evidence: `README.md`)
- Bot runtime → Telegram API: polls and replies (evidence: `tbot.py`)
- Bot runtime → Welcome and help: dispatches commands (evidence: `tbot.py`)
- Bot runtime → Rates replies: dispatches commands (evidence: `tbot.py`)
- Bot runtime → Converter prompts: dispatches commands (evidence: `tbot.py`)
- Bot runtime → Chat clearing: dispatches commands (evidence: `tbot.py`)
- Welcome and help → Telegram API: sends welcome and help (evidence: `tbot.py`)
- Welcome and help → Currency buttons: includes buttons (evidence: `tbot.py`)
- Currency buttons → Rates replies: requests currency rate (evidence: `tbot.py`)
- Rates replies → In-memory rates: reads rows and timestamp (evidence: `tbot.py`)
- Rates replies → Rate and time formatting: formats rate response (evidence: `tbot.py`)
- Rate and time formatting → Telegram API: sends formatted reply (evidence: `tbot.py`)
- Converter prompts → Chat flow state: updates flow state (evidence: `tbot.py`)
- Converter prompts → Amount parsing: parses entered amount (evidence: `tbot.py`)
- Converter prompts → In-memory rates: reads conversion rates (evidence: `tbot.py`)
- Converter prompts → AMD conversion: converts amount (evidence: `tbot.py`)
- AMD conversion → Rate and time formatting: provides result (evidence: `tbot.py`)
- Converter prompts → Telegram API: prompts and sends result (evidence: `tbot.py`)
- Chat clearing → Chat flow state: resets unfinished flow (evidence: `tbot.py`)
- Chat clearing → Telegram API: deletes messages (evidence: `tbot.py`)
- Bot runtime → Refresh lifecycle: starts and closes (evidence: `tbot.py`)
- Refresh lifecycle → Browser scrape: runs refresh scrape (evidence: `scraper.py`)
- Browser scrape → Headless Chrome: loads and reads page (evidence: `scraper.py`)
- Browser scrape → rate.am: fetches rate rows (evidence: `scraper.py`)
- Refresh lifecycle → In-memory rates: stores refreshed rows (evidence: `scraper.py`)
