# mksmin/atomlab-bot architecture

> Architecture diagram of the GitHub repository mksmin/atomlab-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mksmin/atomlab-bot
- Repository: https://github.com/mksmin/atomlab-bot

## Overview

##### Project type and purpose
- This is a single-service, backend-only Telegram bot (“Бот-администратор для проекта Атом-лаб”) written in Python.
- Its primary function is to manage and automate group chats: register new chats, broadcast admin messages, and handle user-level commands (karma, start).

##### File structure
- Top level: run.py (entrypoint), Dockerfile, docker-compose.yaml, config folder, alembic migrations, app folder.
- app/handlers (user/admin handlers), app/database (models, CRUD, helper), app/middlewares, app/keyboards, app/messages, app/statesuser.
- config: .env template + parser to load DB URL, bot token, ROOT user IDs.
- alembic: database versioning / migration scripts.

##### README insights
- Uses asynchronous PostgreSQL (asyncpg + SQLAlchemy).
- Key bot commands divided into user handlers and admin handlers.
- RootProtect middleware for admin authentication.

##### Main components & their relationships
a. Components:
- Telegram API (external)
- Bot Service (Docker container)
– run.py: initializes asyncio event loop, dispatcher, attaches middlewares
– Handlers: user (/start, +rep), admin (/rpanel, /send, /addchat, /chatid, /checkme)
– Middlewares: RootProtect for admin auth
– States & Keyboards: state machine for multi-step commands
– Database module:
· models.py (SQLAlchemy ORM definitions)
· crud_manager/request/db_helper: async CRUD operations
– Config module: loads .env variables (token, DB URL, root IDs)
- PostgreSQL Database (Docker service)
- Alembic (migration tool, runs separately or as part of startup)

b. Interactions & data flow:
1. Bot Service → Telegram API: receives Updates via webhook or long polling
2. Dispatcher routes an Update to a specific handler
3. Handler logic → Database module: read/write chat/user records
4. Database module → PostgreSQL: executes async queries
5. Handler → Telegram API: sends messages back to user or multiple chats (in /send)
6. Alembic (out-of-band): updates DB schema as code evolves

c. Architectural patterns & principles
- Event-driven (handlers respond to incoming updates)
- Separation of concerns:
- Handlers vs. middlewares vs. state management vs. data layer
- Async I/O: non-blocking DB & network calls
- Configuration via environment variables (12-factor style)
- Database migrations automated with Alembic

d. Key technologies & libraries
- Python 3.x, asyncio
- aiogram (Telegram bot framework)
- SQLAlchemy + asyncpg, Alembic
- Docker & docker-compose

##### Final advice
- Be thorough: capture every distinct module (handlers, middlewares, states, data layer).
- Authentication flow for admin commands through the RootProtect middleware.
- Don’t overthink: a clear separation into Telegram API, Bot Service sub-components, and Database will convey the architecture concisely.
- Optional: annotate versioning (Alembic) and configuration sources (.env → config parser).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    TelegramAPI["Telegram API"]:::external
    Alembic["Alembic"]:::tool

    %% Bot Service Container
    subgraph "Bot Service" 
        direction TB
        EntryPoint["Entry Point\n(run.py)"]:::code
        ConfigLoader["Configuration Loader\n(config modules)"]:::code
        Dispatcher["Dispatcher"]:::code
        Middleware["RootProtect Middleware\n(app/middlewares.py)"]:::code
        UserHandlers["User Handlers\n(app/handlers/users.py)"]:::code
        AdminHandlers["Admin Handlers"]:::code
        StateKeyboards["State Machine & Keyboards"]:::code
        DBAccess["DB Access Layer\n(models, CRUD, helpers)"]:::code
    end

    %% Database
    PostgreSQL["PostgreSQL Database"]:::db

    %% Relationships
    TelegramAPI -->|"Update"| EntryPoint
    EntryPoint -->|"loads config"| ConfigLoader
    EntryPoint -->|"init dispatcher"| Dispatcher
    Dispatcher -->|"apply middleware"| Middleware
    Middleware -->|"route to handlers"| UserHandlers
    Middleware -->|"route to handlers"| AdminHandlers
    UserHandlers -->|"use states/keyboards"| StateKeyboards
    AdminHandlers -->|"use states/keyboards"| StateKeyboards
    UserHandlers -->|"async query"| DBAccess
    AdminHandlers -->|"async query"| DBAccess
    DBAccess -->|"execute SQL"| PostgreSQL
    UserHandlers -->|"sendMessage"| TelegramAPI
    AdminHandlers -->|"sendMessage"| TelegramAPI
    Alembic -->|"migration"| PostgreSQL

    %% Click Events
    click EntryPoint "https://github.com/mksmin/atomlab-bot/blob/master/run.py"
    click ConfigLoader "https://github.com/mksmin/atomlab-bot/blob/master/config/config.py"
    click ConfigLoader "https://github.com/mksmin/atomlab-bot/blob/master/config/parser_settings.py"
    click ConfigLoader "https://github.com/mksmin/atomlab-bot/blob/master/config/.env.template"
    click Middleware "https://github.com/mksmin/atomlab-bot/blob/master/app/middlewares.py"
    click UserHandlers "https://github.com/mksmin/atomlab-bot/blob/master/app/handlers/users.py"

    %% Styles
    classDef code fill:#cce5ff,stroke:#2b6cb0,color:#2b6cb0
    classDef db fill:#d4edda,stroke:#276749,color:#276749,stroke-width:2px
    classDef external fill:#f0f0f0,stroke:#718096,color:#4a5568,stroke-dasharray: 5 5
    classDef tool fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:2px
```
