# thevery-nvg/auto_posting_bot architecture

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

- Interactive diagram: https://gitdiagram.com/thevery-nvg/auto_posting_bot
- Repository: https://github.com/thevery-nvg/auto_posting_bot

## Overview

This repository implements a Telegram bot for managing channels and scheduled posts, with webhook and polling entry points. A user interacts through bot updates; handlers manage channel and post records, while scheduling and publication are represented in the source tree. The sampled webhook source establishes dispatcher setup, middleware, and router registration; sampled handlers show database-backed edits. Several major modules are unsampled, so their internal call wiring is not asserted.

Main entry points: [`run_webhook.py`](https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_webhook.py) (Update dispatcher), [`src/handlers/manage_posts`](https://github.com/thevery-nvg/auto_posting_bot/tree/master/src/handlers/manage_posts) (Post management), [`src/core/crud.py`](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/crud.py) (Data operations), [`src/middlewares/db_middleware.py`](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/middlewares/db_middleware.py) (DB middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot runtime"]
  node_webhook["Webhook app<br/>[run_webhook.py]"]
  node_polling["Polling runner<br/>[run_polling.py]"]
  node_dispatcher["Update dispatcher<br/>[run_webhook.py]"]
  node_dbmiddleware["DB middleware<br/>[db_middleware.py]"]
end

subgraph group_interaction["Bot features"]
  node_channel_handlers["Channel management"]
  node_post_handlers["Post management"]
  node_admin["Admin handlers<br/>[admin.py]"]
  node_common["Common commands<br/>[common.py]"]
  node_calendar["Calendar interaction<br/>[calendar.py]"]
end

subgraph group_persistence["Persistence"]
  node_crud["Data operations<br/>[crud.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("Database sessions<br/>[database.py]")]
end

subgraph group_publishing["Scheduling"]
  node_scheduler["Post scheduling<br/>[shedule.py]"]
end

node_user(("Telegram user"))
node_telegram(("Telegram"))
node_botapi(("Telegram Bot API"))

node_user -->|"sends updates"| node_telegram
node_telegram -.->|"posts updates"| node_webhook
node_webhook -->|"feeds updates"| node_dispatcher
node_polling -->|"dispatches updates"| node_dispatcher
node_dispatcher -->|"runs middleware"| node_dbmiddleware
node_dispatcher -->|"routes updates"| node_channel_handlers
node_dispatcher -->|"routes updates"| node_post_handlers
node_dispatcher -->|"routes updates"| node_admin
node_dispatcher -->|"routes updates"| node_common
node_dispatcher -->|"routes updates"| node_calendar
node_dbmiddleware -->|"opens session"| node_database
node_dbmiddleware -->|"shares manager"| node_scheduler
node_channel_handlers -->|"updates records"| node_crud
node_post_handlers -->|"updates records"| node_crud
node_crud -->|"operates on"| node_models
node_crud -->|"persists data"| node_database
node_post_handlers -->|"uses scheduling"| node_scheduler
node_scheduler -->|"publishes posts"| node_botapi
node_post_handlers -->|"sends bot actions"| node_botapi
node_botapi -->|"calls API"| node_telegram

click node_webhook "https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_webhook.py"
click node_polling "https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_polling.py"
click node_dispatcher "https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_webhook.py"
click node_dbmiddleware "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/middlewares/db_middleware.py"
click node_channel_handlers "https://github.com/thevery-nvg/auto_posting_bot/tree/master/src/handlers/manage_channels"
click node_post_handlers "https://github.com/thevery-nvg/auto_posting_bot/tree/master/src/handlers/manage_posts"
click node_admin "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/admin.py"
click node_common "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/common.py"
click node_calendar "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/calendar.py"
click node_crud "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/crud.py"
click node_models "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/models.py"
click node_database "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/database.py"
click node_scheduler "https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/manage_posts/shedule.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_webhook,node_polling,node_dispatcher,node_dbmiddleware,node_user toneBlue
class node_channel_handlers,node_post_handlers,node_admin,node_common,node_calendar toneAmber
class node_crud,node_models,node_database,node_botapi toneMint
class node_scheduler toneRose
class node_telegram toneIndigo
```

## Components

### Bot runtime

- [Webhook app](https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_webhook.py): `run_webhook.py`
- [Polling runner](https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_polling.py): `run_polling.py`
- [Update dispatcher](https://github.com/thevery-nvg/auto_posting_bot/blob/master/run_webhook.py): `run_webhook.py`
- [DB middleware](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/middlewares/db_middleware.py): `src/middlewares/db_middleware.py`

### Bot features

- [Channel management](https://github.com/thevery-nvg/auto_posting_bot/tree/master/src/handlers/manage_channels): `src/handlers/manage_channels`
- [Post management](https://github.com/thevery-nvg/auto_posting_bot/tree/master/src/handlers/manage_posts): `src/handlers/manage_posts`
- [Admin handlers](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/admin.py): `src/handlers/admin.py`
- [Common commands](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/common.py): `src/handlers/common.py`
- [Calendar interaction](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/calendar.py): `src/handlers/calendar.py`

### Persistence

- [Data operations](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/crud.py): `src/core/crud.py`
- [Domain models](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/models.py): `src/core/models.py`
- [Database sessions](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/core/database.py): `src/core/database.py`

### Scheduling

- [Post scheduling](https://github.com/thevery-nvg/auto_posting_bot/blob/master/src/handlers/manage_posts/shedule.py): `src/handlers/manage_posts/shedule.py`

### Other components

- **Telegram user**
- **Telegram**
- **Telegram Bot API**

## Connections

- Telegram user → Telegram: sends updates
- Telegram → Webhook app: posts updates
- Webhook app → Update dispatcher: feeds updates
- Polling runner → Update dispatcher: dispatches updates
- Update dispatcher → DB middleware: runs middleware
- Update dispatcher → Channel management: routes updates
- Update dispatcher → Post management: routes updates
- Update dispatcher → Admin handlers: routes updates
- Update dispatcher → Common commands: routes updates
- Update dispatcher → Calendar interaction: routes updates
- DB middleware → Database sessions: opens session
- DB middleware → Post scheduling: shares manager
- Channel management → Data operations: updates records
- Post management → Data operations: updates records
- Data operations → Domain models: operates on
- Data operations → Database sessions: persists data
- Post management → Post scheduling: uses scheduling
- Post scheduling → Telegram Bot API: publishes posts
- Post management → Telegram Bot API: sends bot actions
- Telegram Bot API → Telegram: calls API