# ashab-al/vacantist-bot_ashab architecture

> Architecture diagram of the GitHub repository ashab-al/vacantist-bot_ashab, 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/ashab-al/vacantist-bot_ashab
- Repository: https://github.com/ashab-al/vacantist-bot_ashab

## Overview

Вакантист — Telegram-бот для выбора категорий вакансий, получения публикаций и покупки поинтов; рядом работает административный HTTP API для управления данными и приёма вакансий и платежных вебхуков. Основной путь: Telegram присылает обновления приложению, бот обрабатывает выбор категорий и доставляет подходящие вакансии; отдельный путь — создание вакансии через API с последующей отправкой. Граф также показывает оплату, модерацию спама и внутренние данные. Связи ограничены README и показанными либо индексированными ссылками; детали некоторых обработчиков и сервисов не проверялись.

Main entry points: [`app/api`](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/api) (API routes), [`app/main.py`](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/main.py) (FastAPI entry), [`app/bot/handlers/payment.py`](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/bot/handlers/payment.py) (Telegram payments), [`app/bot/handlers`](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/bot/handlers) (Bot handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Запуск и API"]
  node_app_entry["FastAPI entry<br/>[main.py]"]
  node_api_routes["API routes"]
  node_bot_runtime["Bot runtime<br/>[create_bot.py]"]
end

subgraph group_telegram["Telegram-продукт"]
  node_bot_handlers["Bot handlers"]
  node_category_flow["Category subscriptions"]
  node_vacancy_browse["Vacancy browsing<br/>[send_vacancies.py]"]
  node_vacancy_delivery["Vacancy delivery<br/>[sender_vacancy.py]"]
  node_spam_moderation["Spam moderation"]
end

subgraph group_operations["Администрирование и оплата"]
  node_api_categories["Category management"]
  node_api_users["User administration"]
  node_api_vacancies["Vacancy intake"]
  node_telegram_payment["Telegram payments<br/>[payment.py]"]
  node_yookassa_payment["YooKassa webhook"]
end

subgraph group_data["Данные и хранилище"]
  node_models["Domain models"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_vacancy_queries["Vacancy queries"]
end

node_telegram_user(("Пользователь Telegram"))
node_api_client(("API-клиент"))
node_telegram_platform{{"Telegram"}}
node_yookassa{{"YooKassa"}}
node_postgres[("PostgreSQL")]

node_telegram_user -->|"sends updates"| node_telegram_platform
node_telegram_platform -->|"posts webhook"| node_app_entry
node_app_entry -->|"starts bot"| node_bot_runtime
node_app_entry -->|"mounts routes"| node_api_routes
node_app_entry -->|"registers handlers"| node_bot_handlers
node_bot_handlers -.->|"sends replies"| node_telegram_platform
node_telegram_user -->|"chooses categories"| node_category_flow
node_category_flow -->|"gets earlier vacancies"| node_vacancy_browse
node_category_flow -->|"receives new vacancies"| node_vacancy_delivery
node_api_client -->|"calls endpoints"| node_api_routes
node_api_routes -->|"creates vacancy"| node_api_vacancies
node_api_vacancies -->|"requests sending"| node_vacancy_delivery
node_api_routes -.->|"manages categories"| node_api_categories
node_api_routes -.->|"manages users"| node_api_users
node_telegram_user -->|"selects tariff"| node_telegram_payment
node_telegram_payment -->|"sends invoice"| node_telegram_platform
node_telegram_platform -->|"confirms checkout"| node_telegram_payment
node_yookassa -->|"posts payment event"| node_api_routes
node_api_routes -->|"processes event"| node_yookassa_payment
node_yookassa_payment -->|"uses bot"| node_bot_runtime
node_bot_handlers -.->|"routes complaint"| node_spam_moderation
node_spam_moderation -->|"looks up vacancy"| node_vacancy_queries
node_api_routes -->|"opens sessions"| node_db_session
node_db_session -->|"creates engine"| node_postgres
node_vacancy_queries -->|"queries models"| node_models
node_telegram_payment -->|"uses session"| node_db_session

click node_app_entry "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/main.py"
click node_api_routes "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/api"
click node_bot_runtime "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/bot/create_bot.py"
click node_bot_handlers "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/bot/handlers"
click node_category_flow "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/user/update_subscription_with_category.py"
click node_vacancy_browse "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/send_vacancies.py"
click node_vacancy_delivery "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/sender_vacancy.py"
click node_spam_moderation "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/send_spam_vacancy_in_admin_group.py"
click node_api_categories "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/category"
click node_api_users "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/user"
click node_api_vacancies "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/vacancy"
click node_telegram_payment "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/bot/handlers/payment.py"
click node_yookassa_payment "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/api/yookassa/payment_processing.py"
click node_models "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/models"
click node_db_session "https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/database.py"
click node_vacancy_queries "https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/query_objects/vacancies"

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_app_entry,node_api_routes,node_bot_runtime toneBlue
class node_bot_handlers,node_category_flow,node_vacancy_browse,node_vacancy_delivery,node_spam_moderation,node_postgres toneAmber
class node_api_categories,node_api_users,node_api_vacancies,node_telegram_payment,node_yookassa_payment,node_api_client toneMint
class node_models,node_db_session,node_vacancy_queries toneRose
class node_telegram_user,node_telegram_platform,node_yookassa toneIndigo
```

## Components

### Запуск и API

- [FastAPI entry](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/api): `app/api`
- [Bot runtime](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/bot/create_bot.py): `app/bot/create_bot.py`

### Telegram-продукт

- [Bot handlers](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/bot/handlers): `app/bot/handlers`
- [Category subscriptions](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/user/update_subscription_with_category.py): `app/services/tg/user/update_subscription_with_category.py`
- [Vacancy browsing](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/send_vacancies.py): `app/services/tg/vacancy/send_vacancies.py`
- [Vacancy delivery](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/sender_vacancy.py): `app/services/tg/vacancy/sender_vacancy.py`
- [Spam moderation](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/tg/vacancy/send_spam_vacancy_in_admin_group.py): `app/services/tg/vacancy/send_spam_vacancy_in_admin_group.py`

### Администрирование и оплата

- [Category management](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/category): `app/services/api/category`
- [User administration](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/user): `app/services/api/user`
- [Vacancy intake](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/services/api/vacancy): `app/services/api/vacancy`
- [Telegram payments](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/bot/handlers/payment.py): `app/bot/handlers/payment.py`
- [YooKassa webhook](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/services/api/yookassa/payment_processing.py): `app/services/api/yookassa/payment_processing.py`

### Данные и хранилище

- [Domain models](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/models): `app/models`
- [Database sessions](https://github.com/ashab-al/vacantist-bot_ashab/blob/main/app/database.py): `app/database.py`
- [Vacancy queries](https://github.com/ashab-al/vacantist-bot_ashab/tree/main/app/query_objects/vacancies): `app/query_objects/vacancies`

### Other components

- **Пользователь Telegram**
- **API-клиент**
- **Telegram**
- **YooKassa**
- **PostgreSQL**

## Connections

- Пользователь Telegram → Telegram: sends updates
- Telegram → FastAPI entry: posts webhook (evidence: `app/main.py`)
- FastAPI entry → Bot runtime: starts bot (evidence: `app/main.py`)
- FastAPI entry → API routes: mounts routes (evidence: `app/main.py`)
- FastAPI entry → Bot handlers: registers handlers (evidence: `app/main.py`)
- Bot handlers → Telegram: sends replies
- Пользователь Telegram → Category subscriptions: chooses categories
- Category subscriptions → Vacancy browsing: gets earlier vacancies
- Category subscriptions → Vacancy delivery: receives new vacancies
- API-клиент → API routes: calls endpoints
- API routes → Vacancy intake: creates vacancy (evidence: `app/api/vacancies/create.py`)
- Vacancy intake → Vacancy delivery: requests sending (evidence: `app/api/vacancies/create.py`)
- API routes → Category management: manages categories
- API routes → User administration: manages users (evidence: `app/api/users/set_status.py`)
- Пользователь Telegram → Telegram payments: selects tariff (evidence: `app/bot/handlers/payment.py`)
- Telegram payments → Telegram: sends invoice (evidence: `app/bot/handlers/payment.py`)
- Telegram → Telegram payments: confirms checkout (evidence: `app/bot/handlers/payment.py`)
- YooKassa → API routes: posts payment event (evidence: `app/api/yookassa/success.py`)
- API routes → YooKassa webhook: processes event (evidence: `app/api/yookassa/success.py`)
- YooKassa webhook → Bot runtime: uses bot (evidence: `app/services/api/yookassa/payment_processing.py`)
- Bot handlers → Spam moderation: routes complaint
- Spam moderation → Vacancy queries: looks up vacancy (evidence: `app/services/tg/vacancy/send_spam_vacancy_in_admin_group.py`)
- API routes → Database sessions: opens sessions (evidence: `app/api/vacancies/create.py`)
- Database sessions → PostgreSQL: creates engine (evidence: `app/database.py`)
- Vacancy queries → Domain models: queries models (evidence: `app/query_objects/vacancies/vacancies_for_the_week.py`)
- Telegram payments → Database sessions: uses session (evidence: `app/bot/handlers/payment.py`)
