🚀 Aiogram 3 Bot Template

A production-ready template for building Telegram bots with Python and Aiogram 3. Includes a clean project structure, database layer, middlewares, and ready-to-use Docker integration.

---

📦 Tech Stack

• Python 3.12
• Aiogram 3.x – asynchronous Telegram Bot framework
• Aiogram Dialog – dialog/GUI framework for Telegram bots
• Dynaconf – flexible configuration management
• PostgreSQL – relational database
• SQLAlchemy + Alembic – ORM and database migrations
• Redis – cache & Taskiq result backend
• Docker & Docker Compose – containerization

---

📂 Project Structure

bot_template/
├── alembic/                    # Alembic migration environment
├── db/                         # Database layer
│   └── repositories/           # Repository classes for models
├── dialogs/                    # Dialogs (aiogram_dialog)
│   └── user_menu/              # Example user menu dialog
├── filters/                    # Custom filters
├── handlers/                   # Handlers for commands and events
├── keyboards/                  # Inline and reply keyboards
├── middlewares/                # Custom middlewares
├── services/                   # Business logic
├── states/                     # FSM states
├── utils/                      # Helper functions and utilities
├── bot.py                      # Main entrypoint
├── config.py                   # Dynaconf settings loader
├── config.toml                 # Project config
├── docker-compose.yml          # Docker Compose config
├── Dockerfile                  # Docker image config
└── requirements.txt            # Python dependencies

---

⚙️ Installation

1. Clone the repository

# via HTTPS
git clone https://github.com/czbag/aiogram-bot-template.git

# or via SSH
git clone git@github.com:czbag/aiogram-bot-template.git

2. Configure environment

Create a .env file in the project root and copy values from .env.example.
Fill in required secrets (e.g. BOT_TOKEN, REDIS_PASSWORD, etc).

3. Run with Docker

Make sure you have Docker and Docker Compose installed:

docker compose up

4. Setup local environment (optional)

Create a virtual environment in the project root and activate it.
Install dependencies:

# pip
pip install .

# or poetry
poetry install --no-root

5. Database migrations

Generate initial migration:

alembic revision --autogenerate -m "init"

Apply migrations:

alembic upgrade head

6. Run the bot

python bot.py

---

🛠️ Features

• Modular and scalable project structure
• Custom middlewares and filters
• Repository pattern for database access
• Alembic migrations built-in
• Dockerized for quick deployment

---

📌 Next Steps

This template is a starting point — extend it with the functionality your bot requires 🚀