# david-lor/vigobus-telegrambot architecture

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

- Interactive diagram: https://gitdiagram.com/david-lor/vigobus-telegrambot
- Repository: https://github.com/david-lor/vigobus-telegrambot

## Overview

VigoBus-TelegramBot is an async Telegram backend for searching Vigo bus stops, showing real-time arrivals, and managing saved stops. Users enter through Telegram messages, inline queries, or callback buttons; handlers invoke stop lookup or saved-stop operations and generate replies. Separate features support stop renaming, feedback, and user-data export/deletion. The README documents the external VigoBus and Persistence APIs and MongoDB-backed request logs. Some runtime wiring is unsampled, so edges not supported by excerpts or README are omitted.

Main entry points: [`vigobusbot/telegram_bot/handlers/message_handlers.py`](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/message_handlers.py) (Message handlers), [`vigobusbot/persistence_api/saved_stops/saved_stops_manager.py`](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/persistence_api/saved_stops/saved_stops_manager.py) (Saved stops), [`vigobusbot/telegram_bot/services/message_generators`](https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/telegram_bot/services/message_generators) (Reply generation), [`vigobusbot/telegram_bot/handlers/callback_handlers.py`](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/callback_handlers.py) (Button handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot_runtime["Bot runtime"]
  node_entrypoint["Application startup<br/>[entrypoint.py]"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_polling["Update delivery<br/>[polling.py]"]
end

subgraph group_user_interactions["User interactions"]
  node_message_handlers["Message handlers"]
  node_inline_handlers["Inline handlers<br/>[inline_handlers.py]"]
  node_callback_handlers["Button handlers"]
  node_request_handling["Request controls<br/>[request_handler.py]"]
  node_message_generation["Reply generation"]
  node_rename_feedback["Rename and feedback"]
end

subgraph group_transit_data["Transit data"]
  node_stop_lookup["Stop lookup<br/>[stop_getter.py]"]
  node_bus_lookup["Bus arrivals<br/>[bus_getter.py]"]
end

subgraph group_persistence["Persistence"]
  node_saved_stops["Saved stops"]
  node_saved_stop_encoding["Saved-stop encoding<br/>[encoder.py]"]
  node_message_state["Sent-message state"]
end

subgraph group_operations["Bot operations"]
  node_static_content["Static content"]
  node_settings["Configuration<br/>[__init__.py]"]
  node_logging["Request logging<br/>[logger.py]"]
end

node_user(("Telegram user"))
node_telegram{{"Telegram platform"}}
node_vigo_api{{"VigoBus API"}}
node_persistence_api{{"Persistence API"}}
node_mongo_logs[("MongoDB logs")]

node_user -->|"sends updates"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_entrypoint -.->|"starts"| node_bot
node_entrypoint -->|"loads"| node_static_content
node_bot -.->|"runs"| node_polling
node_polling -.->|"receives updates"| node_telegram
node_message_handlers -->|"wraps requests"| node_request_handling
node_callback_handlers -->|"wraps requests"| node_request_handling
node_message_handlers -->|"generates replies"| node_message_generation
node_callback_handlers -->|"generates replies"| node_message_generation
node_inline_handlers -->|"generates results"| node_message_generation
node_message_handlers -->|"handles replies"| node_rename_feedback
node_callback_handlers -->|"updates saved stops"| node_saved_stops
node_rename_feedback -->|"renames stops"| node_saved_stops
node_rename_feedback -->|"refreshes message"| node_message_generation
node_message_generation -.->|"formats stop replies"| node_stop_lookup
node_message_handlers -.->|"searches stops"| node_stop_lookup
node_stop_lookup -->|"requests stop data"| node_vigo_api
node_bus_lookup -.->|"requests arrival data"| node_vigo_api
node_message_handlers -->|"manages saved stops"| node_saved_stops
node_saved_stops -->|"encodes records"| node_saved_stop_encoding
node_saved_stops -->|"persists stops"| node_persistence_api
node_message_state -->|"uses encoding"| node_saved_stop_encoding
node_message_handlers -.->|"tracks messages"| node_message_state
node_logging -->|"persists request logs"| node_mongo_logs
node_logging -->|"reads settings"| node_settings

click node_entrypoint "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/entrypoint.py"
click node_bot "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/bot.py"
click node_polling "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/polling.py"
click node_message_handlers "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/message_handlers.py"
click node_inline_handlers "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/inline_handlers.py"
click node_callback_handlers "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/callback_handlers.py"
click node_request_handling "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/services/generic_request_handler/request_handler.py"
click node_message_generation "https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/telegram_bot/services/message_generators"
click node_rename_feedback "https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/telegram_bot/services"
click node_stop_lookup "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/vigobus_api/stop_getter.py"
click node_bus_lookup "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/vigobus_api/bus_getter.py"
click node_saved_stops "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/persistence_api/saved_stops/saved_stops_manager.py"
click node_saved_stop_encoding "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/persistence_api/saved_stops/services/encoder.py"
click node_message_state "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/services/sent_messages_persistence.py"
click node_static_content "https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/static_handler"
click node_settings "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/settings_handler/__init__.py"
click node_logging "https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/logger.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_entrypoint,node_bot,node_polling,node_user toneBlue
class node_message_handlers,node_inline_handlers,node_callback_handlers,node_request_handling,node_message_generation,node_rename_feedback,node_mongo_logs toneAmber
class node_stop_lookup,node_bus_lookup,node_vigo_api,node_persistence_api toneMint
class node_saved_stops,node_saved_stop_encoding,node_message_state toneRose
class node_static_content,node_settings,node_logging,node_telegram toneIndigo
```

## Components

### Bot runtime

- [Application startup](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/entrypoint.py): `vigobusbot/entrypoint.py`
- [Bot runtime](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/bot.py): `vigobusbot/telegram_bot/bot.py`
- [Update delivery](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/polling.py): `vigobusbot/telegram_bot/polling.py`

### User interactions

- [Message handlers](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/message_handlers.py): `vigobusbot/telegram_bot/handlers/message_handlers.py`
- [Inline handlers](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/inline_handlers.py): `vigobusbot/telegram_bot/handlers/inline_handlers.py`
- [Button handlers](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/handlers/callback_handlers.py): `vigobusbot/telegram_bot/handlers/callback_handlers.py`
- [Request controls](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/services/generic_request_handler/request_handler.py): `vigobusbot/telegram_bot/services/generic_request_handler/request_handler.py`
- [Reply generation](https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/telegram_bot/services/message_generators): `vigobusbot/telegram_bot/services/message_generators`
- [Rename and feedback](https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/telegram_bot/services): `vigobusbot/telegram_bot/services`

### Transit data

- [Stop lookup](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/vigobus_api/stop_getter.py): `vigobusbot/vigobus_api/stop_getter.py`
- [Bus arrivals](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/vigobus_api/bus_getter.py): `vigobusbot/vigobus_api/bus_getter.py`

### Persistence

- [Saved stops](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/persistence_api/saved_stops/saved_stops_manager.py): `vigobusbot/persistence_api/saved_stops/saved_stops_manager.py`
- [Saved-stop encoding](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/persistence_api/saved_stops/services/encoder.py): `vigobusbot/persistence_api/saved_stops/services/encoder.py`
- [Sent-message state](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/telegram_bot/services/sent_messages_persistence.py): `vigobusbot/telegram_bot/services/sent_messages_persistence.py`

### Bot operations

- [Static content](https://github.com/david-lor/vigobus-telegrambot/tree/develop/vigobusbot/static_handler): `vigobusbot/static_handler`
- [Configuration](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/settings_handler/__init__.py): `vigobusbot/settings_handler/__init__.py`
- [Request logging](https://github.com/david-lor/vigobus-telegrambot/blob/develop/vigobusbot/logger.py): `vigobusbot/logger.py`

### Other components

- **Telegram user**
- **Telegram platform**
- **VigoBus API**
- **Persistence API**
- **MongoDB logs**

## Connections

- Telegram user → Telegram platform: sends updates
- Telegram platform → Bot runtime: delivers updates
- Application startup → Bot runtime: starts
- Application startup → Static content: loads (evidence: `vigobusbot/entrypoint.py`)
- Bot runtime → Update delivery: runs
- Update delivery → Telegram platform: receives updates
- Message handlers → Request controls: wraps requests (evidence: `vigobusbot/telegram_bot/handlers/message_handlers.py`)
- Button handlers → Request controls: wraps requests (evidence: `vigobusbot/telegram_bot/handlers/callback_handlers.py`)
- Message handlers → Reply generation: generates replies (evidence: `vigobusbot/telegram_bot/handlers/message_handlers.py`)
- Button handlers → Reply generation: generates replies (evidence: `vigobusbot/telegram_bot/handlers/callback_handlers.py`)
- Inline handlers → Reply generation: generates results (evidence: `vigobusbot/telegram_bot/handlers/inline_handlers.py`)
- Message handlers → Rename and feedback: handles replies (evidence: `vigobusbot/telegram_bot/handlers/message_handlers.py`)
- Button handlers → Saved stops: updates saved stops (evidence: `vigobusbot/telegram_bot/handlers/callback_handlers.py`)
- Rename and feedback → Saved stops: renames stops (evidence: `vigobusbot/telegram_bot/services/stop_rename_request_handler.py`)
- Rename and feedback → Reply generation: refreshes message (evidence: `vigobusbot/telegram_bot/services/stop_rename_request_handler.py`)
- Reply generation → Stop lookup: formats stop replies
- Message handlers → Stop lookup: searches stops
- Stop lookup → VigoBus API: requests stop data (evidence: `vigobusbot/vigobus_api/stop_getter.py`)
- Bus arrivals → VigoBus API: requests arrival data
- Message handlers → Saved stops: manages saved stops (evidence: `vigobusbot/telegram_bot/handlers/message_handlers.py`)
- Saved stops → Saved-stop encoding: encodes records (evidence: `vigobusbot/persistence_api/saved_stops/saved_stops_manager.py`)
- Saved stops → Persistence API: persists stops
- Sent-message state → Saved-stop encoding: uses encoding (evidence: `vigobusbot/telegram_bot/services/sent_messages_persistence.py`)
- Message handlers → Sent-message state: tracks messages (evidence: `vigobusbot/telegram_bot/handlers/message_handlers.py`)
- Request logging → MongoDB logs: persists request logs (evidence: `vigobusbot/logger.py`)
- Request logging → Configuration: reads settings (evidence: `vigobusbot/logger.py`)
