How mksmin/atomlab-bot works
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).