# ghostoraner/bot-assistant-via-telegramm architecture

> Architecture diagram of the GitHub repository ghostoraner/bot-assistant-via-telegramm, 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/ghostoraner/bot-assistant-via-telegramm
- Repository: https://github.com/ghostoraner/bot-assistant-via-telegramm

## Overview

A Telegram long-polling assistant routes user messages into menu/settings, job search, task and planner management, or Groq chat. Search collects and category-filters listings from freelance sources; users can save a result to the planner. Handlers read and write user, task, and planner records through async SQLAlchemy sessions, while locale helpers supply RU/EN text. The graph follows README-described runtime capabilities and excerpted calls; source-level evidence for middleware wiring and the additional AI service wrapper was not shown, so those links are omitted.

Main entry points: [`app/main.py`](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/main.py) (Polling dispatcher), [`app/handlers/job_search.py`](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/job_search.py) (Job search handler), [`app/handlers/menu.py`](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/menu.py) (Menu and settings), [`app/database/engine.py`](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/database/engine.py) (Async DB sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Polling dispatcher<br/>[main.py]"]
end

subgraph group_features["User features"]
  node_menu["Menu and settings<br/>[menu.py]"]
  node_ai["AI chat handler<br/>[ai_chat.py]"]
  node_jobs["Job search handler<br/>[job_search.py]"]
  node_tasks["Tasks and planner<br/>[tasks_planner.py]"]
end

subgraph group_services["External services"]
  node_telegram{{"Telegram Bot API"}}
  node_parser["Listing parser<br/>[parser_service.py]"]
  node_sources{{"Freelance sources"}}
  node_groq{{"Groq chat API"}}
end

subgraph group_persistence["Persistence and language"]
  node_locales["RU/EN messages<br/>[locales.py]"]
  node_engine["Async DB sessions<br/>[engine.py]"]
  node_models["User/task/plan models<br/>[models.py]"]
  node_mysql[("MySQL database")]
end

node_user(("Telegram user"))

node_user -->|"sends messages"| node_telegram
node_telegram -->|"delivers updates"| node_entry
node_entry -->|"long polls"| node_telegram
node_entry -->|"registers router"| node_menu
node_entry -->|"registers router"| node_ai
node_entry -->|"registers router"| node_jobs
node_entry -->|"registers router"| node_tasks
node_menu -->|"opens sessions"| node_engine
node_menu -->|"reads and updates"| node_models
node_menu -->|"gets messages"| node_locales
node_ai -->|"gets language and keyboard"| node_menu
node_ai -->|"gets messages"| node_locales
node_ai -->|"requests completion"| node_groq
node_jobs -->|"requests listings"| node_parser
node_parser -->|"fetches listings"| node_sources
node_jobs -->|"opens sessions"| node_engine
node_jobs -->|"saves planner entry"| node_models
node_jobs -->|"gets messages"| node_locales
node_tasks -->|"opens sessions"| node_engine
node_tasks -->|"queries and writes"| node_models
node_tasks -->|"gets messages"| node_locales
node_engine -->|"connects asynchronously"| node_mysql
node_engine -.->|"uses mapped entities"| node_models

click node_entry "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/main.py"
click node_menu "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/menu.py"
click node_ai "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/ai_chat.py"
click node_jobs "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/job_search.py"
click node_tasks "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/tasks_planner.py"
click node_parser "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/services/parser_service.py"
click node_locales "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/locales.py"
click node_engine "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/database/engine.py"
click node_models "https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/database/models.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_entry,node_user toneBlue
class node_menu,node_ai,node_jobs,node_tasks toneAmber
class node_telegram,node_parser,node_sources,node_groq toneMint
class node_locales,node_engine,node_models,node_mysql toneRose
```

## Components

### Bot runtime

- [Polling dispatcher](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/main.py): `app/main.py`

### User features

- [Menu and settings](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/menu.py): `app/handlers/menu.py`
- [AI chat handler](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/ai_chat.py): `app/handlers/ai_chat.py`
- [Job search handler](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/job_search.py): `app/handlers/job_search.py`
- [Tasks and planner](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/handlers/tasks_planner.py): `app/handlers/tasks_planner.py`

### External services

- **Telegram Bot API**
- [Listing parser](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/services/parser_service.py): `app/services/parser_service.py`
- **Freelance sources**
- **Groq chat API**

### Persistence and language

- [RU/EN messages](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/locales.py): `app/locales.py`
- [Async DB sessions](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/database/engine.py): `app/database/engine.py`
- [User/task/plan models](https://github.com/ghostoraner/bot-assistant-via-telegramm/blob/main/app/database/models.py): `app/database/models.py`
- **MySQL database**

### Other components

- **Telegram user**

## Connections

- Telegram user → Telegram Bot API: sends messages (evidence: `README.md`)
- Telegram Bot API → Polling dispatcher: delivers updates (evidence: `README.md`)
- Polling dispatcher → Telegram Bot API: long polls (evidence: `app/main.py`)
- Polling dispatcher → Menu and settings: registers router (evidence: `app/main.py`)
- Polling dispatcher → AI chat handler: registers router (evidence: `app/main.py`)
- Polling dispatcher → Job search handler: registers router (evidence: `app/main.py`)
- Polling dispatcher → Tasks and planner: registers router (evidence: `app/main.py`)
- Menu and settings → Async DB sessions: opens sessions (evidence: `app/handlers/menu.py`)
- Menu and settings → User/task/plan models: reads and updates (evidence: `app/handlers/menu.py`)
- Menu and settings → RU/EN messages: gets messages (evidence: `app/handlers/menu.py`)
- AI chat handler → Menu and settings: gets language and keyboard (evidence: `app/handlers/ai_chat.py`)
- AI chat handler → RU/EN messages: gets messages (evidence: `app/handlers/ai_chat.py`)
- AI chat handler → Groq chat API: requests completion (evidence: `app/handlers/ai_chat.py`)
- Job search handler → Listing parser: requests listings (evidence: `app/handlers/job_search.py`)
- Listing parser → Freelance sources: fetches listings (evidence: `app/services/parser_service.py`)
- Job search handler → Async DB sessions: opens sessions (evidence: `app/handlers/job_search.py`)
- Job search handler → User/task/plan models: saves planner entry (evidence: `app/handlers/job_search.py`)
- Job search handler → RU/EN messages: gets messages (evidence: `app/handlers/job_search.py`)
- Tasks and planner → Async DB sessions: opens sessions (evidence: `app/handlers/tasks_planner.py`)
- Tasks and planner → User/task/plan models: queries and writes (evidence: `app/handlers/tasks_planner.py`)
- Tasks and planner → RU/EN messages: gets messages (evidence: `app/handlers/tasks_planner.py`)
- Async DB sessions → MySQL database: connects asynchronously (evidence: `README.md`)
- Async DB sessions → User/task/plan models: uses mapped entities
