Telegram Bot Enterprise Boilerplate: aiogram 3.x Template

Every Telegram bot project starts the same way: a handler file that grows into a 1000-line monolith, business logic tangled directly in message handlers, no transaction safety, and zero structure to onboard a second developer. Junior teams copy-paste from tutorials; senior teams rebuild the same foundation from scratch on every project.

The Cost: 2–3 weeks of architecture setup per project, technical debt from day one, and zero consistency across a team's bot portfolio.

A production-grade, strictly-structured boilerplate for aiogram 3.x Telegram bots that enforces Clean Architecture from the first line of code. Handlers are routing-only. All business logic lives in services. Database access is wrapped in Unit of Work transactions. Background tasks, i18n, anti-spam middleware, and Docker are all pre-wired — clone, configure, ship.

Architecture pattern: Clean Architecture — Handlers → Services → Repositories → Models

Transaction safety: Unit of Work (UoW) — atomic commits across all DB operations

ORM: SQLAlchemy 2.0 async + asyncpg

Background tasks: Taskiq + Redis broker, fully wired

Middleware stack: DB injection, i18n, anti-spam throttling

Localization: Fluent (.ftl) + validation + auto-fix scripts

Containerization: Multi-stage Docker build, non-root user, health checks

Security: Pydantic settings, parameterized queries, env-based secrets

Handlers are transport-only — they receive a message and delegate immediately to a service. The boilerplate enforces this with concrete before/after examples showing the wrong pattern (logic in handler) and the correct pattern (handler calls service). New team members internalize this boundary from the first PR.

All database operations within a single request are wrapped in one SQLAlchemyUoW context. Middleware injects the UoW into every handler automatically — no manual session management, no partial commits, no forgotten rollbacks.

Localization uses Mozilla's Fluent format across en, uk, and ru locales. Two utility scripts ship with the boilerplate: check_i18n.py reports missing translation keys per language, and auto_fix_i18n.py syncs them automatically — preventing silent translation gaps from shipping to production.

The Dockerfile uses a two-stage build (builder + runtime) with a non-root appuser, no cache bloat, and separate volumes for logs. Docker Compose wires four services out of the box: PostgreSQL 15, Redis 7, the bot process, and the Taskiq background worker — with health checks on the infrastructure tier.

Bot Framework: aiogram 3.4+ with webhook support

Database: PostgreSQL 15 + SQLAlchemy 2.0 async + asyncpg, Alembic migrations

Cache / Broker: Redis 7 (FSM storage + Taskiq task queue)

Background Tasks: Taskiq with Redis ListQueueBroker

Config: Pydantic Settings with SecretStr — all secrets in .env, never hardcoded

Localization: Fluent (.ftl files) + aiogram-i18n middleware

Security: Anti-spam throttling middleware, parameterized SQLAlchemy queries, non-root Docker container, ADMIN_IDS access control

Code Quality: PEP 8, type hints throughout, docstrings on public methods

Freelancers & Agencies: Stop rebuilding the same foundation. Clone, configure .env, and start writing product features on day one — architecture decisions are already made and documented.

Teams Scaling Bot Development: Enforce consistent patterns across multiple developers and multiple projects. Every bot in the portfolio follows the same layer rules, making onboarding and code review predictable.

SaaS Founders Building on Telegram: Use as the backend scaffold for subscription bots, e-commerce bots, or community tools — premium/subscription infrastructure, i18n, and background task processing are pre-wired.