# duama20180/weather_bot architecture

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

- Interactive diagram: https://gitdiagram.com/duama20180/weather_bot
- Repository: https://github.com/duama20180/weather_bot

## Overview

Weather Bot is a Telegram assistant for location-based current weather, AI clothing advice, and scheduled notifications. Users share a location or enter a place name, then request a forecast or tips, or configure a daily schedule. The handlers coordinate these interactions and persist user settings; a background scheduler checks saved times and sends weather and optional tips. The README documents these capabilities, while sampled source confirms the principal calls. Location lookup uses Gemini and forecast retrieval uses Weatherstack; unsampled details are represented only where documented.

Main entry points: [`main.py`](https://github.com/duama20180/weather_bot/blob/master/main.py) (Bot startup), [`app/handlers.py`](https://github.com/duama20180/weather_bot/blob/master/app/handlers.py) (Message handlers), [`app/scheduler.py`](https://github.com/duama20180/weather_bot/blob/master/app/scheduler.py) (Reminder scheduler), [`app/forecast.py`](https://github.com/duama20180/weather_bot/blob/master/app/forecast.py) (Weather reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Bot startup<br/>[main.py]"]
  node_config["Environment config<br/>[config.py]"]
end

subgraph group_interaction["User interaction"]
  node_handlers["Message handlers<br/>[handlers.py]"]
  node_keyboards["Bot keyboards<br/>[keyboards.py]"]
end

subgraph group_weather["Weather and advice"]
  node_location["Location lookup<br/>[forecast.py]"]
  node_forecast["Weather reports<br/>[forecast.py]"]
  node_adviser["Clothing advice<br/>[ai_adviser.py]"]
end

subgraph group_persistence["Persistence and scheduling"]
  node_dbsetup["Database setup<br/>[db_create.py]"]
  node_dbhandlers["User data access<br/>[db_handlers.py]"]
  node_database[("PostgreSQL users")]
  node_scheduler["Reminder scheduler<br/>[scheduler.py]"]
end

node_user(("Telegram user"))
node_weatherstack["Weatherstack API"]
node_gemini["Gemini AI"]
node_telegram["Telegram platform"]

node_user -->|"sends requests"| node_main
node_main -->|"creates schema"| node_dbsetup
node_main -->|"initializes database"| node_dbhandlers
node_main -->|"registers router"| node_handlers
node_main -->|"starts checker"| node_scheduler
node_main -->|"starts polling"| node_telegram
node_handlers -->|"uses keyboards"| node_keyboards
node_handlers -->|"resolves place"| node_location
node_handlers -->|"requests weather"| node_forecast
node_handlers -->|"requests tips"| node_adviser
node_handlers -->|"reads and saves settings"| node_dbhandlers
node_location -->|"looks up coordinates"| node_gemini
node_forecast -->|"fetches conditions"| node_weatherstack
node_forecast -->|"formats report"| node_gemini
node_adviser -->|"generates advice"| node_gemini
node_scheduler -->|"reads locations"| node_dbhandlers
node_scheduler -->|"fetches reports"| node_forecast
node_scheduler -->|"requests enabled tips"| node_adviser
node_scheduler -->|"sends reminders"| node_telegram
node_dbsetup -->|"creates database and table"| node_database
node_dbhandlers -->|"reads and updates users"| node_database
node_dbhandlers -->|"uses connection settings"| node_config
node_forecast -->|"uses API keys"| node_config
node_adviser -->|"uses AI key"| node_config

click node_main "https://github.com/duama20180/weather_bot/blob/master/main.py"
click node_handlers "https://github.com/duama20180/weather_bot/blob/master/app/handlers.py"
click node_keyboards "https://github.com/duama20180/weather_bot/blob/master/app/keyboards.py"
click node_location "https://github.com/duama20180/weather_bot/blob/master/app/forecast.py"
click node_forecast "https://github.com/duama20180/weather_bot/blob/master/app/forecast.py"
click node_adviser "https://github.com/duama20180/weather_bot/blob/master/app/ai_adviser.py"
click node_config "https://github.com/duama20180/weather_bot/blob/master/app/config.py"
click node_dbsetup "https://github.com/duama20180/weather_bot/blob/master/app/db_create.py"
click node_dbhandlers "https://github.com/duama20180/weather_bot/blob/master/app/db_handlers.py"
click node_scheduler "https://github.com/duama20180/weather_bot/blob/master/app/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_main,node_config,node_user toneBlue
class node_handlers,node_keyboards toneAmber
class node_location,node_forecast,node_adviser,node_weatherstack toneMint
class node_dbsetup,node_dbhandlers,node_database,node_scheduler toneRose
class node_gemini,node_telegram toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/duama20180/weather_bot/blob/master/main.py): `main.py`
- [Environment config](https://github.com/duama20180/weather_bot/blob/master/app/config.py): `app/config.py`

### User interaction

- [Message handlers](https://github.com/duama20180/weather_bot/blob/master/app/handlers.py): `app/handlers.py`
- [Bot keyboards](https://github.com/duama20180/weather_bot/blob/master/app/keyboards.py): `app/keyboards.py`

### Weather and advice

- [Location lookup](https://github.com/duama20180/weather_bot/blob/master/app/forecast.py): `app/forecast.py`
- [Weather reports](https://github.com/duama20180/weather_bot/blob/master/app/forecast.py): `app/forecast.py`
- [Clothing advice](https://github.com/duama20180/weather_bot/blob/master/app/ai_adviser.py): `app/ai_adviser.py`

### Persistence and scheduling

- [Database setup](https://github.com/duama20180/weather_bot/blob/master/app/db_create.py): `app/db_create.py`
- [User data access](https://github.com/duama20180/weather_bot/blob/master/app/db_handlers.py): `app/db_handlers.py`
- **PostgreSQL users**
- [Reminder scheduler](https://github.com/duama20180/weather_bot/blob/master/app/scheduler.py): `app/scheduler.py`

### Other components

- **Telegram user**
- **Weatherstack API**
- **Gemini AI**
- **Telegram platform**

## Connections

- Telegram user → Bot startup: sends requests (evidence: `README.md`)
- Bot startup → Database setup: creates schema (evidence: `main.py`)
- Bot startup → User data access: initializes database (evidence: `main.py`)
- Bot startup → Message handlers: registers router (evidence: `main.py`)
- Bot startup → Reminder scheduler: starts checker (evidence: `main.py`)
- Bot startup → Telegram platform: starts polling (evidence: `main.py`)
- Message handlers → Bot keyboards: uses keyboards (evidence: `app/handlers.py`)
- Message handlers → Location lookup: resolves place (evidence: `app/handlers.py`)
- Message handlers → Weather reports: requests weather (evidence: `app/handlers.py`)
- Message handlers → Clothing advice: requests tips (evidence: `app/handlers.py`)
- Message handlers → User data access: reads and saves settings (evidence: `app/handlers.py`)
- Location lookup → Gemini AI: looks up coordinates (evidence: `app/forecast.py`)
- Weather reports → Weatherstack API: fetches conditions (evidence: `app/forecast.py`)
- Weather reports → Gemini AI: formats report (evidence: `app/forecast.py`)
- Clothing advice → Gemini AI: generates advice (evidence: `app/ai_adviser.py`)
- Reminder scheduler → User data access: reads locations (evidence: `app/scheduler.py`)
- Reminder scheduler → Weather reports: fetches reports (evidence: `app/scheduler.py`)
- Reminder scheduler → Clothing advice: requests enabled tips (evidence: `app/scheduler.py`)
- Reminder scheduler → Telegram platform: sends reminders (evidence: `app/scheduler.py`)
- Database setup → PostgreSQL users: creates database and table (evidence: `app/db_create.py`)
- User data access → PostgreSQL users: reads and updates users (evidence: `app/db_handlers.py`)
- User data access → Environment config: uses connection settings (evidence: `app/db_handlers.py`)
- Weather reports → Environment config: uses API keys (evidence: `app/forecast.py`)
- Clothing advice → Environment config: uses AI key (evidence: `app/ai_adviser.py`)
