Aiogram Bot Template

📌 Description

⠀

Aiogram Bot Template — This template helps you quickly bootstrap Telegram bots on the aiogram 3.x stack. It already includes a ready project structure, command and message handlers, optional PostgreSQL/Redis integration, logging with loguru, internationalization, support for aiogram-dialog, and dependency injection via dishka with optional webhook handling on FastAPI. The template is designed to remove routine setup and let you focus on your bot’s logic.

⠀

🔨 Functions

⠀

/start - Start the bot
/language - Change language
/help - Help
/admin - Command for administrators
/dialog - Demo dialog using aiogram-dialog
/fsm - Demo finite state machine form

⠀

🗂️ Template structure

⠀

📁 aiogram_bot_template/
├───┐ 📂 .github/
│   ├───┐ 📂 ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └───┐ 📂 workflows/
│       ├── ci.yml
│       └── docker.yml
│
├───┐ 📂 docs/
│   ├── getting-started.md
│   ├── README.md
│   ├───┐ 📂 guides/
│   ├───┐ 📂 reference/
│   └───┐ 📂 releases/
│
├───┐ 📂 migrations/
│   ├── env.py
│   └───┐ 📂 versions/
│
├───┐ 📂 scripts/
│   ├── create_migration.sh
│   ├── db_seed.py
│   └── health_check.py
│
├───┐ 📂 source/
│   ├───┐ 📂 config/
│   │   ├── __init__.py
│   │   └── config_reader.py
│   │
│   ├───┐ 📂 constants/
│   │   ├── __init__.py
│   │   ├── logging.py
│   │   └── throttling.py
│   │
│   ├───┐ 📂 data/
│   │   ├── __init__.py
│   │   ├── 📂 error_logs/
│   │   └── 📂 full_logs/
│   │
│   ├───┐ 📂 database/
│   │   ├───┐ 📂 core/
│   │   │   └── __init__.py
│   │   │
│   │   ├───┐ 📂 models/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   └── user.py
│   │   │
│   │   ├───┐ 📂 repositories/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   └── user.py
│   │   │
│   │   ├───┐ 📂 specifications/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   └── user.py
│   │   │
│   │   ├───┐ 📂 tools/
│   │   │   ├── __init__.py
│   │   │   ├── mixin.py
│   │   │   └── uow.py
│   │   │
│   │   └── __init__.py
│   │
│   ├───┐ 📂 domain/
│   │   ├── __init__.py
│   │   ├── events.py
│   │   ├── exceptions.py
│   │   └── value_objects.py
│   │
│   ├───┐ 📂 dto/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── user.py
│   │
│   ├───┐ 📂 enums/
│   │   ├── __init__.py
│   │   └── roles.py
│   │
│   ├───┐ 📂 factory/
│   │   ├── __init__.py
│   │   ├── bot.py
│   │   ├── container.py
│   │   ├── dispatcher.py
│   │   ├── dishka.py
│   │   └── server.py
│   │
│   ├───┐ 📂 infrastructure/
│   │   ├── __init__.py
│   │   ├───┐ 📂 cache/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   └── redis.py
│   │   │
│   │   └───┐ 📂 monitoring/
│   │       ├── __init__.py
│   │       └── prometheus.py
│   │
│   ├───┐ 📂 locales/
│   │   ├───┐ 📂 en/
│   │   │   ├── buttons.ftl
│   │   │   └── messages.ftl
│   │   └───┐ 📂 ru/
│   │       ├── buttons.ftl
│   │       └── messages.ftl
│   │
│   ├───┐ 📂 services/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── cache_service.py
│   │   └── user_service.py
│   │
│   ├───┐ 📂 telegram/
│   │   ├───┐ 📂 filters/
│   │   │   ├── __init__.py
│   │   │   ├── admin.py
│   │   │   ├── admin_protect.py
│   │   │   ├── chat_type.py
│   │   │   └── validators.py
│   │   │
│   │   ├───┐ 📂 handlers/
│   │   │   ├───┐ 📂 admin/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── callbacks.py
│   │   │   │   ├── commands.py
│   │   │   │   ├── fsm.py
│   │   │   │   └── messages.py
│   │   │   ├───┐ 📂 errors/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── common.py
│   │   │   │   ├── orm.py
│   │   │   │   └── telegram.py
│   │   │   └───┐ 📂 user/
│   │   │       ├── __init__.py
│   │   │       ├── callbacks.py
│   │   │       ├── commands.py
│   │   │       ├── fsm.py
│   │   │       └── messages.py
│   │   │
│   │   ├───┐ 📂 keyboards/
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   ├── builder.py
│   │   │   ├── callback_factory.py
│   │   │   ├── inline.py
│   │   │   └── reply.py
│   │   │
│   │   ├───┐ 📂 middlewares/
│   │   │   ├── __init__.py
│   │   │   ├── auth.py
│   │   │   ├── base.py
│   │   │   ├── reporting.py
│   │   │   └── throttling.py
│   │   │
│   │   ├───┐ 📂 states/
│   │   │   ├── __init__.py
│   │   │   ├── dialog.py
│   │   │   └── form.py
│   │   │
│   │   └───┐ 📂 dialogs/
│   │       ├── __init__.py
│   │       └── dialog.py
│   │
│   ├───┐ 📂 utils/
│   │   ├── __init__.py
│   │   ├── logger.py
│   │   ├── set_commands.py
│   │   ├── translator.py
│   │   └── validators.py
│   │
│   └── 📄 __main__.py
│
├───┐ 📂 tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├───┐ 📂 e2e/
│   ├───┐ 📂 integration/
│   └───┐ 📂 unit/
│
├── alembic.ini
├── .env.example
├── .dockerignore
├── .gitignore
├── .pre-commit-config.yaml
├── docker-compose.dev.yml
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── Makefile
├── pyproject.toml
├── README.md
├── reorganize-docs.sh
├── SECURITY.md
└── uv.lock

⠀

📋 About the content

⠀

📁 source/ - Main application source code.
📁 source/config/ - Application configuration settings.
📁 source/constants/ - Project constants.
📁 source/data/ - Data generated by the application (e.g., logs).
📁 source/data/error_logs/ - Log files containing only errors.
📁 source/data/full_logs/ - Full log files.
📁 source/database/ - Database interaction logic.
📁 source/database/core/ - Database core modules (connection, sessions).
📁 source/database/models/ - Database model definitions.
📁 source/database/repositories/ - Repositories for database data access.
📁 source/database/specifications/ - Query specifications.
📁 source/database/tools/ - Helper tools for working with the database.
📁 source/domain/ - Domain events and value objects.
📁 source/dto/ - Data transfer objects.
📁 source/enums/ - Enum definitions.
📁 source/factory/ - Factories for creating the bot, dispatcher, webhook server and DI container.
📁 source/infrastructure/ - External integrations (cache, monitoring).
📁 source/locales/ - Localization files (translations).
📁 source/locales/en/ - English language localization.
📁 source/locales/ru/ - Russian language localization.
📁 source/services/ - Business logic layer.
📁 source/telegram/ - Components related to Telegram and aiogram.
📁 source/telegram/filters/ - Custom aiogram filters.
📁 source/telegram/handlers/ - Handlers for processing Telegram updates.
📁 source/telegram/handlers/admin/ - Handlers for administrators.
📁 source/telegram/handlers/errors/ - Error handlers.
📁 source/telegram/handlers/user/ - Handlers for users.
📁 source/telegram/keyboards/ - Telegram keyboards.
📁 source/telegram/middlewares/ - aiogram middlewares (throttling, error reporting).
📁 source/telegram/states/ - aiogram FSM states.
📁 source/telegram/dialogs/ - Dialog windows built with aiogram-dialog.
📁 source/utils/ - Helper utilities (logger setup, commands, translations).
📄 source/__main__.py - Main entry point within the source package.
📄 .env.example - Example file for sensitive data (.env).
📁 docs/ - Development and deployment documentation.
📁 scripts/ - Helper scripts for development tasks.
📁 tests/ - Test suite.

⠀

⚙️ Configuration

⠀

Before running the bot, you need to set up your environment variables. Copy the .env.example file to .env and fill in your credentials and settings:

cp .env.example .env
# Then edit the .env file with your configurations

⠀

🔓 Bot .env Variables

⠀

Environment Variable Name	Description
ENVIRONMENT	Application environment (`development`, `test`, `production`).
TG__WEBHOOK_USE	Boolean value (`True`/`False`) indicating whether to use webhooks (`True`) or long polling (`False`).
TG__WEBHOOK_PATH	Path for Telegram to send webhook updates (appended to `WEBHOOK__URL`).
TG__BOT_TOKEN	Your Telegram bot token, obtained from `@BotFather` in Telegram.
TG__ADMIN_IDS	List of Telegram user IDs (JSON list or comma-separated) who will have administrator rights in the bot.
WEBHOOK__URL	Public URL where Telegram will send updates if webhooks are enabled.
WEBHOOK__HOST	Host or IP address where the webhook server will listen for incoming connections (usually `0.0.0.0`).
WEBHOOK__PORT	Port on which the webhook server will listen for incoming connections.
WEBHOOK__PATH	Specific path on the server where Telegram will send POST requests with updates.
WEBHOOK__SECRET	Secret token that Telegram includes in webhook request headers to verify authenticity.
DB__HOST	Database server host.
DB__PORT	Port for connecting to the database.
DB__USER	Username for database authentication.
DB__PASSWORD	Password for database authentication.
DB__NAME	Name of the database to connect to.
REDIS__HOST	Redis server host used for FSM and/or caching.
REDIS__PORT	Port for connecting to the Redis server.
REDIS__USER	Username for Redis authentication (if used).
REDIS__PASSWORD	Password for Redis authentication (if used).
REDIS__DB	Redis database index to use (a number from 0 to 15, default is 0).

⠀

💻 Bot Setup

⠀

📦 Using UV

⠀

Clone the repository and navigate into the project directory:

 git clone https://github.com/MrConsoleka/aiogram-bot-template.git
 cd aiogram-bot-template

Ensure you have uv installed. If not, you can install it, for example, using pip:
```
pip install uv
```
Create a virtual environment:
```
make venv
```

Activate the virtual environment:

# For Linux or macOS:
source .venv/bin/activate

# For Windows:
.venv\Scripts\activate

Install dependencies:
```
make install
```
To run the bot, use the command:
```
make run
```

⠀

📦 Using Docker

⠀

Clone the repository and navigate into the project directory:

git clone https://github.com/MrConsoleka/aiogram-bot-template.git
cd aiogram-bot-template

Build the Docker Image:
```
make docker-build
```
Run the Project with Docker Compose:
```
make docker-up
```

Verify Bot is Running (Optional):

make docker-logs

make docker-logs SERVICE=bot

Stop the Project:
```
make docker-down
```

⠀

🗄️ Migrations

⠀

Create and apply migrations with Alembic:

make migration MESSAGE="create users"
uv run alembic upgrade head

⠀

🧪 Testing

⠀

Run tests locally:

uv run pytest tests/

⠀

🧰 Pre-commit

⠀

pre-commit install
pre-commit run --all-files

⠀

🧩 Development Services

⠀

make dev-up
make dev-down

⠀

📋 Todo List

⠀

touch the grass
Alembic
Aiogram-dialog
.github/workflows

⠀

🗃️ Stack of Technologies

⠀

aiogram-3x - Asynchronous framework for the Telegram Bot API.
aiogram-dialog - Dialog manager for building interactive flows.
dishka - Dependency injection container.
fastapi & uvicorn - Webhook server stack.
pydantic & pydantic-settings - Data validation and configuration management.
postgresql with sqlalchemy and asyncpg - Database layer.
redis - In-memory data store for FSM and caching.
loguru - Logging library.
prometheus-client - Metrics exporter (optional).
cachetools & fluentogram - Caching and localization helpers.
Ruff, Mypy, Pre-commit, Isort, Black - Code quality and formatting tools.

⠀

💼 Credits

⠀

aiogram_template - Inspired by Abdullah's project, many thanks to him <3

⠀

MrConsoleka/aiogram-bot-template