# iringil/open-weather-bot architecture

> Architecture diagram of the GitHub repository iringil/open-weather-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iringil/open-weather-bot
- Repository: https://github.com/iringil/open-weather-bot

## Overview

Open Weather Bot is a Telegram weather-forecast bot. A user starts a setup dialog, searches by city name or location, selects a city and units, then receives current conditions and a forecast image; saved settings support scheduled updates every three hours. The graph also preserves administration, localization, and supporting data/formatting components. Evidence is limited to the README, the source index, and the excerpts provided; unsampled modules are included only where their role or connection is documented there.

Main entry points: [`bot.py`](https://github.com/iringil/open-weather-bot/blob/master/bot.py) (Webhook bot), [`tgbot/services/weather.py`](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/weather.py) (Weather service), [`tgbot/services/database.py`](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/database.py) (User database), [`tgbot/handlers/dialog.py`](https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/dialog.py) (Setup dialog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot entry and interaction"]
  node_bot["Webhook bot<br/>[bot.py]"]
  node_dialog["Setup dialog<br/>[dialog.py]"]
  node_commands["User commands<br/>[commands.py]"]
  node_admin["Admin handlers<br/>[admin.py]"]
  node_admin_filter["Admin filter<br/>[admin.py]"]
  node_keyboards["Inline keyboards<br/>[inline.py]"]
end

subgraph group_weather["Weather workflow"]
  node_weather_service["Weather service<br/>[weather.py]"]
  node_parser["Weather parser<br/>[parser.py]"]
  node_formatter["Weather formatter<br/>[formatter.py]"]
  node_image["Forecast image<br/>[image.py]"]
end

subgraph group_support["User state and localization"]
  node_models["Weather data types<br/>[classes.py]"]
  node_database["User database<br/>[database.py]"]
  node_localization["Localization middleware<br/>[localization.py]"]
  node_translations["Translations"]
end

subgraph group_operations["Operations"]
  node_config["Configuration<br/>[config.py]"]
  node_scheduler["Weather scheduler<br/>[scheduler.py]"]
end

node_user(("Telegram user"))
node_telegram(("Telegram"))
node_weather_api(("OpenWeather API"))
node_postgres[("PostgreSQL")]
node_redis[("Redis FSM storage")]

node_user -->|"sends requests"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"registers handlers"| node_dialog
node_bot -->|"registers handlers"| node_commands
node_bot -->|"registers handlers"| node_admin
node_bot -->|"binds filter"| node_admin_filter
node_bot -->|"sets middleware"| node_localization
node_bot -->|"starts schedule"| node_scheduler
node_bot -->|"creates tables"| node_database
node_bot -->|"loads settings"| node_config
node_dialog -->|"requests weather"| node_weather_service
node_dialog -->|"reads and saves"| node_database
node_dialog -->|"builds choices"| node_keyboards
node_keyboards -->|"uses city data"| node_models
node_weather_service -->|"requests data"| node_weather_api
node_weather_service -->|"loads settings"| node_database
node_weather_service -->|"parses responses"| node_parser
node_weather_service -->|"formats conditions"| node_formatter
node_weather_service -->|"renders forecast"| node_image
node_parser -->|"creates data types"| node_models
node_formatter -->|"formats data types"| node_models
node_image -->|"uses weather data"| node_models
node_database -->|"queries records"| node_postgres
node_scheduler -->|"refreshes forecasts"| node_weather_service
node_scheduler -->|"loads users"| node_database
node_admin -->|"manages users"| node_database
node_localization -->|"loads messages"| node_translations
node_config -->|"configures storage"| node_redis
node_bot -->|"sets webhook"| node_telegram

click node_bot "https://github.com/iringil/open-weather-bot/blob/master/bot.py"
click node_dialog "https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/dialog.py"
click node_commands "https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/commands.py"
click node_admin "https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/admin.py"
click node_admin_filter "https://github.com/iringil/open-weather-bot/blob/master/tgbot/filters/admin.py"
click node_keyboards "https://github.com/iringil/open-weather-bot/blob/master/tgbot/keyboards/inline.py"
click node_weather_service "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/weather.py"
click node_parser "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/parser.py"
click node_formatter "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/formatter.py"
click node_image "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/image.py"
click node_models "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/classes.py"
click node_database "https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/database.py"
click node_localization "https://github.com/iringil/open-weather-bot/blob/master/tgbot/middlewares/localization.py"
click node_translations "https://github.com/iringil/open-weather-bot/tree/master/tgbot/locales"
click node_config "https://github.com/iringil/open-weather-bot/blob/master/tgbot/config.py"
click node_scheduler "https://github.com/iringil/open-weather-bot/blob/master/tgbot/misc/scheduler.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,node_dialog,node_commands,node_admin,node_admin_filter,node_keyboards,node_user toneBlue
class node_weather_service,node_parser,node_formatter,node_image,node_postgres,node_redis toneAmber
class node_models,node_database,node_localization,node_translations,node_weather_api toneMint
class node_config,node_scheduler toneRose
class node_telegram toneIndigo
```

## Components

### Bot entry and interaction

- [Webhook bot](https://github.com/iringil/open-weather-bot/blob/master/bot.py): `bot.py`
- [Setup dialog](https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/dialog.py): `tgbot/handlers/dialog.py`
- [User commands](https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/commands.py): `tgbot/handlers/commands.py`
- [Admin handlers](https://github.com/iringil/open-weather-bot/blob/master/tgbot/handlers/admin.py): `tgbot/handlers/admin.py`
- [Admin filter](https://github.com/iringil/open-weather-bot/blob/master/tgbot/filters/admin.py): `tgbot/filters/admin.py`
- [Inline keyboards](https://github.com/iringil/open-weather-bot/blob/master/tgbot/keyboards/inline.py): `tgbot/keyboards/inline.py`

### Weather workflow

- [Weather service](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/weather.py): `tgbot/services/weather.py`
- [Weather parser](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/parser.py): `tgbot/services/parser.py`
- [Weather formatter](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/formatter.py): `tgbot/services/formatter.py`
- [Forecast image](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/image.py): `tgbot/services/image.py`

### User state and localization

- [Weather data types](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/classes.py): `tgbot/services/classes.py`
- [User database](https://github.com/iringil/open-weather-bot/blob/master/tgbot/services/database.py): `tgbot/services/database.py`
- [Localization middleware](https://github.com/iringil/open-weather-bot/blob/master/tgbot/middlewares/localization.py): `tgbot/middlewares/localization.py`
- [Translations](https://github.com/iringil/open-weather-bot/tree/master/tgbot/locales): `tgbot/locales`

### Operations

- [Configuration](https://github.com/iringil/open-weather-bot/blob/master/tgbot/config.py): `tgbot/config.py`
- [Weather scheduler](https://github.com/iringil/open-weather-bot/blob/master/tgbot/misc/scheduler.py): `tgbot/misc/scheduler.py`

### Other components

- **Telegram user**
- **Telegram**
- **OpenWeather API**
- **PostgreSQL**
- **Redis FSM storage**

## Connections

- Telegram user → Telegram: sends requests (evidence: `README.md`)
- Telegram → Webhook bot: delivers updates (evidence: `bot.py`)
- Webhook bot → Setup dialog: registers handlers (evidence: `bot.py`)
- Webhook bot → User commands: registers handlers (evidence: `bot.py`)
- Webhook bot → Admin handlers: registers handlers (evidence: `bot.py`)
- Webhook bot → Admin filter: binds filter (evidence: `bot.py`)
- Webhook bot → Localization middleware: sets middleware (evidence: `bot.py`)
- Webhook bot → Weather scheduler: starts schedule (evidence: `bot.py`)
- Webhook bot → User database: creates tables (evidence: `bot.py`)
- Webhook bot → Configuration: loads settings (evidence: `bot.py`)
- Setup dialog → Weather service: requests weather (evidence: `tgbot/handlers/dialog.py`)
- Setup dialog → User database: reads and saves (evidence: `tgbot/handlers/dialog.py`)
- Setup dialog → Inline keyboards: builds choices (evidence: `tgbot/handlers/dialog.py`)
- Inline keyboards → Weather data types: uses city data (evidence: `tgbot/keyboards/inline.py`)
- Weather service → OpenWeather API: requests data (evidence: `tgbot/services/weather.py`)
- Weather service → User database: loads settings (evidence: `tgbot/services/weather.py`)
- Weather service → Weather parser: parses responses (evidence: `tgbot/services/weather.py`)
- Weather service → Weather formatter: formats conditions (evidence: `tgbot/services/weather.py`)
- Weather service → Forecast image: renders forecast (evidence: `tgbot/services/weather.py`)
- Weather parser → Weather data types: creates data types (evidence: `tgbot/services/parser.py`)
- Weather formatter → Weather data types: formats data types (evidence: `tgbot/services/formatter.py`)
- Forecast image → Weather data types: uses weather data (evidence: `tgbot/services/image.py`)
- User database → PostgreSQL: queries records (evidence: `tgbot/services/database.py`)
- Weather scheduler → Weather service: refreshes forecasts (evidence: `tgbot/misc/scheduler.py`)
- Weather scheduler → User database: loads users (evidence: `tgbot/misc/scheduler.py`)
- Admin handlers → User database: manages users (evidence: `tgbot/handlers/admin.py`)
- Localization middleware → Translations: loads messages (evidence: `tgbot/middlewares/localization.py`)
- Configuration → Redis FSM storage: configures storage (evidence: `tgbot/config.py`)
- Webhook bot → Telegram: sets webhook (evidence: `bot.py`)
