# ev-zhelak/commonlang_bot architecture

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

- Interactive diagram: https://gitdiagram.com/ev-zhelak/commonlang_bot
- Repository: https://github.com/ev-zhelak/commonlang_bot

## Overview

CommonLang is an under-development Telegram bot whose visible workflow receives text, translates it to English, and replies with the translation. Startup prepares data, initializes a SQLite users table, configures the bot and commands, registers handlers, then polls for updates. The README names translation and bot libraries; sampled code confirms the translation flow and user-table creation, but not persistence of messages or user records. Command-handler behavior and several database operations are not shown, so their internal relationships are omitted.

Main entry points: [`main.py`](https://github.com/ev-zhelak/commonlang_bot/blob/main/main.py) (Application startup), [`app/bot/bot.py`](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/bot/bot.py) (Bot and dispatcher), [`app/database/manager.py`](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/manager.py) (Database manager), [`app/handlers/messages.py`](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/handlers/messages.py) (Text handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Application startup<br/>[main.py]"]
  node_bot["Bot and dispatcher<br/>[bot.py]"]
  node_commands["Command handlers<br/>[commands.py]"]
  node_messages["Text handler<br/>[messages.py]"]
end

subgraph group_translation["Translation"]
  node_translator["Translation helper<br/>[tool.py]"]
end

subgraph group_storage["User storage"]
  node_db_manager["Database manager<br/>[manager.py]"]
  node_db_queries["SQL definitions<br/>[queries.py]"]
  node_models["User and message models<br/>[models.py]"]
end

subgraph group_support["Configuration and support"]
  node_config["Configuration<br/>[config.py]"]
  node_setup["Data setup<br/>[setup.py]"]
  node_logging["Logging utilities<br/>[log.py]"]
end

node_user(("Chat user"))
node_telegram["Telegram API"]
node_translation_service["Google Translate"]
node_sqlite[("SQLite database")]

node_user -->|"sends messages"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_main -->|"runs setup"| node_setup
node_main -->|"creates table"| node_db_manager
node_main -->|"creates dispatcher"| node_bot
node_main -->|"sets commands"| node_bot
node_main -->|"registers handler"| node_commands
node_main -->|"registers handler"| node_messages
node_main -->|"starts polling"| node_bot
node_bot -->|"gets token"| node_config
node_bot -->|"sets commands"| node_telegram
node_messages -->|"translates text"| node_translator
node_translator -->|"requests translation"| node_translation_service
node_messages -->|"replies with translation"| node_telegram
node_db_manager -->|"gets database path"| node_config
node_db_manager -->|"executes table SQL"| node_db_queries
node_db_manager -->|"creates table"| node_sqlite
node_setup -->|"uses decorator"| node_logging
node_logging -->|"gets log level"| node_config

click node_main "https://github.com/ev-zhelak/commonlang_bot/blob/main/main.py"
click node_bot "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/bot/bot.py"
click node_commands "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/handlers/commands.py"
click node_messages "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/handlers/messages.py"
click node_translator "https://github.com/ev-zhelak/commonlang_bot/blob/main/utils/tool.py"
click node_db_manager "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/manager.py"
click node_db_queries "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/queries.py"
click node_models "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/models.py"
click node_config "https://github.com/ev-zhelak/commonlang_bot/blob/main/config/config.py"
click node_setup "https://github.com/ev-zhelak/commonlang_bot/blob/main/app/initialize/setup.py"
click node_logging "https://github.com/ev-zhelak/commonlang_bot/blob/main/utils/log.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_bot,node_commands,node_messages,node_user toneBlue
class node_translator,node_sqlite toneAmber
class node_db_manager,node_db_queries,node_models,node_telegram toneMint
class node_config,node_setup,node_logging toneRose
class node_translation_service toneIndigo
```

## Components

### Bot runtime

- [Application startup](https://github.com/ev-zhelak/commonlang_bot/blob/main/main.py): `main.py`
- [Bot and dispatcher](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/bot/bot.py): `app/bot/bot.py`
- [Command handlers](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/handlers/commands.py): `app/handlers/commands.py`
- [Text handler](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/handlers/messages.py): `app/handlers/messages.py`

### Translation

- [Translation helper](https://github.com/ev-zhelak/commonlang_bot/blob/main/utils/tool.py): `utils/tool.py`

### User storage

- [Database manager](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/manager.py): `app/database/manager.py`
- [SQL definitions](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/queries.py): `app/database/queries.py`
- [User and message models](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/database/models.py): `app/database/models.py`

### Configuration and support

- [Configuration](https://github.com/ev-zhelak/commonlang_bot/blob/main/config/config.py): `config/config.py`
- [Data setup](https://github.com/ev-zhelak/commonlang_bot/blob/main/app/initialize/setup.py): `app/initialize/setup.py`
- [Logging utilities](https://github.com/ev-zhelak/commonlang_bot/blob/main/utils/log.py): `utils/log.py`

### Other components

- **Chat user**
- **Telegram API**
- **Google Translate**
- **SQLite database**

## Connections

- Chat user → Telegram API: sends messages
- Telegram API → Bot and dispatcher: delivers updates
- Application startup → Data setup: runs setup (evidence: `main.py`)
- Application startup → Database manager: creates table (evidence: `main.py`)
- Application startup → Bot and dispatcher: creates dispatcher (evidence: `main.py`)
- Application startup → Bot and dispatcher: sets commands (evidence: `main.py`)
- Application startup → Command handlers: registers handler (evidence: `main.py`)
- Application startup → Text handler: registers handler (evidence: `main.py`)
- Application startup → Bot and dispatcher: starts polling (evidence: `main.py`)
- Bot and dispatcher → Configuration: gets token (evidence: `app/bot/bot.py`)
- Bot and dispatcher → Telegram API: sets commands (evidence: `app/bot/bot.py`)
- Text handler → Translation helper: translates text (evidence: `app/handlers/messages.py`)
- Translation helper → Google Translate: requests translation (evidence: `utils/tool.py`)
- Text handler → Telegram API: replies with translation (evidence: `app/handlers/messages.py`)
- Database manager → Configuration: gets database path (evidence: `app/database/manager.py`)
- Database manager → SQL definitions: executes table SQL (evidence: `app/database/manager.py`)
- Database manager → SQLite database: creates table (evidence: `app/database/manager.py`)
- Data setup → Logging utilities: uses decorator (evidence: `app/initialize/setup.py`)
- Logging utilities → Configuration: gets log level (evidence: `utils/log.py`)
