aiogram-payments-template

This is a template for demonstration how to work with Telegram Payments API using aiogram 3 framework.

❗️ Read HELP.md if something is unclear ❗️

Template uses:

• aiogram 3
• SQLAlchemy + Alembic
• PostgreSQL
• Docker
• uv

---

Installation

Step 1: Clone the repository

git clone https://github.com/andrew000/aiogram-payments-template.git
cd aiogram-payments-template

Step 2: Install dependencies

I recommend using UV to manage your project.

# Create virtual environment using UV
uv venv --python=3.13

# Install dependencies
make sync

Step 3: Create .env file

Create a .env file in the root of the project and fill it with the necessary data.

cp .env.example .env.docker # for docker development
cp .env.example .env # for local development

Step 4: Deploy project

make up

Step 5: Run migrations

Template already has initial migration. To apply it, run the following command:

make upgrade-revision

Step 6: Bot is ready and running

Bot is ready to use. You can check the logs using the following command:

docker compose logs -f

---

Explanation

Project structure

The project structure is as follows:

AIOGRAM-TEMPLATE
├───app (main application)
│   ├───bot (bot)
│   │   ├───errors (error handlers)
│   │   ├───handlers (event handlers)
│   │   ├───main.py (bot entrypoint)
│   │   ├───middlewares (event middlewares)
│   │   ├───pyproject.toml (bot workspace configuration)
│   │   ├───settings.py (bot settings)
│   │   ├───storages (database storages)
│   │   └───utils (utility functions)
│   ├───migrations (alembic migrations)
│   │   ├───alembic.ini (alembic configuration)
│   │   ├───env.py (alembic environment)
│   │   ├───pyproject.toml (alembic workspace configuration)
│   │   └───versions (migration files)
├───psql (PostgreSQL database)
│   ├───data (database data)
│   └───db-init-script (database initialization script)
├───pyproject.toml (project configuration)
├───docker-compose.yml (docker-compose configuration)
├───.env.example (example environment file)
├───.pre-commit-config.yaml (pre-commit configuration)
└───Makefile (make commands)

The bot is located in the app/bot directory. The bot is divided into modules, each of which is responsible for a specific functionality. handlers are responsible for processing events, middlewares for preprocessing events, storages for declaring models and working with the database, errors for error handling.

Migrations

Migration files are located in the app/migrations directory.

❗️ It is recommended to create migrations files before you push your code to the repository.

❗️ Always check your migrations before apply them to the production database.

To create initial migration, check if your models imported in the app/bot/storages/psql/__init__.py file and run the following command:

make create-init-revision

To apply head migration, run the following command:

make upgrade-revision

To apply specific migration, run the following command:

make upgrade-revision rev=<revision_id>

rev_id - id of the migration in the app/migrations/versions directory. Initial migration id is 000000000000.

To check current migration rev_id in the database, run the following command:

make current-revision

Pre-commit

The project uses pre-commit hooks. To install pre-commit hooks, run the following command:

uv run pre-commit install

Docker

The project uses Docker for deployment. To build and run the bot in Docker, run the following command:

make up

Yes, little command to run large project. It will build and run the bot and PostgreSQL containers.

To gracefully stop the bot and remove containers, run the following command:

make down

Webhooks

Bot may use webhooks. To enable webhooks, set WEBHOOKS environment variable to True in the .env file. Also, set WEBHOOK_URL and WEBHOOK_SECRET_TOKEN environment variables.