{"id":27767868,"url":"https://github.com/mrconsoleka/aiogram-bot-template","last_synced_at":"2026-01-07T23:21:29.226Z","repository":{"id":290379279,"uuid":"974235550","full_name":"MrConsoleka/aiogram-bot-template","owner":"MrConsoleka","description":"Template for creating scalable bots with aiogram","archived":false,"fork":false,"pushed_at":"2025-04-29T06:42:21.000Z","size":91,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-29T19:53:44.452Z","etag":null,"topics":["aiogram","aiogram-i18n","aiogram3","aiohttp","asyncpg","docker","loguru","makefile","postgresql","pyproject","python","python3","ruff","template","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrConsoleka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T13:13:00.000Z","updated_at":"2025-04-29T06:42:25.000Z","dependencies_parsed_at":"2025-04-28T14:43:25.583Z","dependency_job_id":"e57b8047-2c28-4f00-9bac-996394d09182","html_url":"https://github.com/MrConsoleka/aiogram-bot-template","commit_stats":null,"previous_names":["mrconsoleka/aiogram-bot-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrConsoleka%2Faiogram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrConsoleka%2Faiogram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrConsoleka%2Faiogram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrConsoleka%2Faiogram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrConsoleka","download_url":"https://codeload.github.com/MrConsoleka/aiogram-bot-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251574675,"owners_count":21611387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","aiogram-i18n","aiogram3","aiohttp","asyncpg","docker","loguru","makefile","postgresql","pyproject","python","python3","ruff","template","uv"],"created_at":"2025-04-29T19:53:50.002Z","updated_at":"2026-01-07T23:21:29.218Z","avatar_url":"https://github.com/MrConsoleka.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"250\" height=\"250\" alt=\"image\" src=\"https://github.com/user-attachments/assets/a67162ea-bf43-4713-a27e-0581a8534b5b\" /\u003e\n\n\u003ch1\u003eAiogram Bot Template\u003c/h1\u003e\n\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/tag-v1.1-8A2BE2?style=flat\u0026logo=task\u0026logoColor=8A2BE2\u0026labelColor=gray\"\u003e\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/python-v3.12-FBDE02?style=flat\u0026logo=python\u0026logoColor=FBDE02\u0026labelColor=gray\"\u003e\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/license-MIT-12C4C4?style=flat\u0026logo=gitbook\u0026logoColor=12C4C4\"\u003e\n\u003cbr\u003e\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/Aiogram-v3.22.0-blue?style=flat\"\u003e\n\n\u003c/div\u003e\n\n## 📌 Description\n⠀\n\n**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.\n\n⠀\n## 🔨 Functions\n⠀\n\n*   `/start` - Start the bot\n*   `/language` - Change language\n*   `/help` - Help\n*   `/admin` - Command for administrators\n*   `/dialog` - Demo dialog using `aiogram-dialog`\n*   `/fsm` - Demo finite state machine form\n\n⠀\n## 🗂️ Template structure\n⠀\n\n```\n📁 aiogram_bot_template/\n├───┐ 📂 .github/\n│   └───┐ 📂 ISSUE_TEMPLATE/\n│       ├── bug_report.md\n│       └── feature_request.md\n│\n├───┐ 📂 source/\n│   ├───┐ 📂 config/\n│   │   ├── __init__.py\n│   │   └── config_reader.py\n│   │\n│   ├───┐ 📂 constants/\n│   │   ├── __init__.py\n│   │   ├── throttling.py\n│   │   └── logging.py\n│   │\n│   ├───┐ 📂 data/\n│   │   ├── __init__.py\n│   │   ├── 📂 error_logs/\n│   │   └── 📂 full_logs/\n│   │\n│   ├───┐ 📂 database/\n│   │   ├───┐ 📂 core/\n│   │   │   ├── __init__.py\n│   │   │   └── manager.py\n│   │   │\n│   │   ├───┐ 📂 models/\n│   │   │   ├── __init__.py\n│   │   │   ├── base.py\n│   │   │   └── user.py\n│   │   │\n│   │   ├───┐ 📂 repositories/\n│   │   │   ├── __init__.py\n│   │   │   ├── base.py\n│   │   │   └── user.py\n│   │   │\n│   │   ├───┐ 📂 tools/\n│   │   │   ├── __init__.py\n│   │   │   ├── mixin.py\n│   │   │   └── uow.py\n│   │   │\n│   │   └── __init__.py\n│   │\n│   ├───┐ 📂 enums/\n│   │   ├── __init__.py\n│   │   └── roles.py\n│   │\n│   ├───┐ 📂 factory/\n│   │   ├── __init__.py\n│   │   ├── bot.py\n│   │   ├── dispatcher.py\n│   │   ├── dishka.py\n│   │   └── server.py\n│   │\n│   ├───┐ 📂 locales/\n│   │   ├───┐ 📂 en/\n│   │   │   ├── buttons.ftl\n│   │   │   └── messages.ftl\n│   │   └───┐ 📂 ru/\n│   │       ├── buttons.ftl\n│   │       └── messages.ftl\n│   │\n│   ├───┐ 📂 services/\n│   │   ├── __init__.py\n│   │   └── user_service.py\n│   │\n│   ├───┐ 📂 telegram/\n│   │   ├───┐ 📂 filters/\n│   │   │   ├── __init__.py\n│   │   │   ├── admin_protect.py\n│   │   │   └── chat_type.py\n│   │   │\n│   │   ├───┐ 📂 handlers/\n│   │   │   ├───┐ 📂 admin/\n│   │   │   │   ├── __init__.py\n│   │   │   │   ├── callbacks.py\n│   │   │   │   ├── commands.py\n│   │   │   │   ├── fsm.py\n│   │   │   │   └── messages.py\n│   │   │   ├───┐ 📂 errors/\n│   │   │   │   ├── __init__.py\n│   │   │   │   ├── common.py\n│   │   │   │   ├── orm.py\n│   │   │   │   └── telegram.py\n│   │   │   └───┐ 📂 user/\n│   │   │       ├── __init__.py\n│   │   │       ├── callbacks.py\n│   │   │       ├── commands.py\n│   │   │       ├── fsm.py\n│   │   │       └── messages.py\n│   │   │\n│   │   ├───┐ 📂 keyboards/\n│   │   │   ├── __init__.py\n│   │   │   ├── builder.py\n│   │   │   ├── callback_factory.py\n│   │   │   ├── inline.py\n│   │   │   └── reply.py\n│   │   │\n│   │   ├───┐ 📂 middlewares/\n│   │   │   ├── __init__.py\n│   │   │   ├── callback_throttling.py\n│   │   │   ├── message_throttling.py\n│   │   │   └── reporting.py\n│   │   │\n│   │   ├───┐ 📂 states/\n│   │   │   ├── __init__.py\n│   │   │   ├── dialog.py\n│   │   │   └── form.py\n│   │   │\n│   │   └───┐ 📂 dialogs/\n│   │       ├── __init__.py\n│   │       └── dialog.py\n│   │\n│   ├───┐ 📂 utils/\n│   │   ├── __init__.py\n│   │   ├── logger.py\n│   │   ├── set_commands.py\n│   │   └── translator.py\n│   │\n│   └── 📄 __main__.py\n│\n├── .env.example\n├── .dockerignore\n├── .gitignore\n├── Dockerfile\n├── LICENSE\n├── Makefile\n├── SECURITY.md\n├── docker-compose.yml\n├── pyproject.toml\n└── README.md\n```\n\n⠀\n## 📋 About the content\n⠀\n\n*   `📁 source/` - Main application source code.\n*   `📁 source/config/` - Application configuration settings.\n*   `📁 source/constants/` - Project constants.\n*   `📁 source/data/` - Data generated by the application (e.g., logs).\n*   `📁 source/data/error_logs/` - Log files containing only errors.\n*   `📁 source/data/full_logs/` - Full log files.\n*   `📁 source/database/` - Database interaction logic.\n*   `📁 source/database/core/` - Database core modules (connection, sessions).\n*   `📁 source/database/models/` - Database model definitions.\n*   `📁 source/database/repositories/` - Repositories for database data access.\n*   `📁 source/database/specifications/` - Query specifications.\n*   `📁 source/database/tools/` - Helper tools for working with the database.\n*   `📁 source/domain/` - Domain events and value objects.\n*   `📁 source/dto/` - Data transfer objects.\n*   `📁 source/enums/` - Enum definitions.\n*   `📁 source/factory/` - Factories for creating the bot, dispatcher, webhook server and DI container.\n*   `📁 source/infrastructure/` - External integrations (cache, monitoring).\n*   `📁 source/locales/` - Localization files (translations).\n*   `📁 source/locales/en/` - English language localization.\n*   `📁 source/locales/ru/` - Russian language localization.\n*   `📁 source/services/` - Business logic layer.\n*   `📁 source/telegram/` - Components related to Telegram and `aiogram`.\n*   `📁 source/telegram/filters/` - Custom `aiogram` filters.\n*   `📁 source/telegram/handlers/` - Handlers for processing Telegram updates.\n*   `📁 source/telegram/handlers/admin/` - Handlers for administrators.\n*   `📁 source/telegram/handlers/errors/` - Error handlers.\n*   `📁 source/telegram/handlers/user/` - Handlers for users.\n*   `📁 source/telegram/keyboards/` - Telegram keyboards.\n*   `📁 source/telegram/middlewares/` - `aiogram` middlewares (throttling, error reporting).\n*   `📁 source/telegram/states/` - `aiogram` FSM states.\n*   `📁 source/telegram/dialogs/` - Dialog windows built with `aiogram-dialog`.\n*   `📁 source/utils/` - Helper utilities (logger setup, commands, translations).\n*   `📄 source/__main__.py` - Main entry point within the `source` package.\n*   `📄 .env.example` - Example file for sensitive data (.env).\n*   `📁 docs/` - Development and deployment documentation.\n*   `📁 scripts/` - Helper scripts for development tasks.\n*   `📁 tests/` - Test suite.\n\n⠀\n## ⚙️ Configuration\n⠀\n\nBefore 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:\n\n```shell\ncp .env.example .env\n# Then edit the .env file with your configurations\n```\n\n⠀\n## 🔓 Bot .env Variables\n⠀\n\n| Environment Variable Name | Description |\n|---------------------------|-------------|\n| ENVIRONMENT               | Application environment (`development`, `test`, `production`). |\n| TG__WEBHOOK_USE           | Boolean value (`True`/`False`) indicating whether to use webhooks (`True`) or long polling (`False`). |\n| TG__WEBHOOK_PATH          | Path for Telegram to send webhook updates (appended to `WEBHOOK__URL`). |\n| TG__BOT_TOKEN             | Your Telegram bot token, obtained from `@BotFather` in Telegram. |\n| TG__ADMIN_IDS             | List of Telegram user IDs (JSON list or comma-separated) who will have administrator rights in the bot. |\n| WEBHOOK__URL              | Public URL where Telegram will send updates if webhooks are enabled. |\n| WEBHOOK__HOST             | Host or IP address where the webhook server will listen for incoming connections (usually `0.0.0.0`). |\n| WEBHOOK__PORT             | Port on which the webhook server will listen for incoming connections. |\n| WEBHOOK__PATH             | Specific path on the server where Telegram will send POST requests with updates. |\n| WEBHOOK__SECRET           | Secret token that Telegram includes in webhook request headers to verify authenticity. |\n| DB__HOST                  | Database server host. |\n| DB__PORT                  | Port for connecting to the database. |\n| DB__USER                  | Username for database authentication. |\n| DB__PASSWORD              | Password for database authentication. |\n| DB__NAME                  | Name of the database to connect to. |\n| REDIS__HOST               | Redis server host used for FSM and/or caching. |\n| REDIS__PORT               | Port for connecting to the Redis server. |\n| REDIS__USER               | Username for Redis authentication (if used). |\n| REDIS__PASSWORD           | Password for Redis authentication (if used). |\n| REDIS__DB                 | Redis database index to use (a number from 0 to 15, default is 0). |\n\n⠀\n## 💻 Bot Setup\n⠀\n\n### 📦 Using UV\n⠀\n1.  Clone the repository and navigate into the project directory:\n\n    ```shell\n     git clone https://github.com/MrConsoleka/aiogram-bot-template.git\n     cd aiogram-bot-template\n    ```\n\n2.  Ensure you have `uv` installed. If not, you can install it, for example, using `pip`:\n\n    ```shell\n    pip install uv\n    ```\n\n3.  Create a virtual environment:\n\n    ```shell\n    make venv\n    ```\n\n4.  Activate the virtual environment:\n\n    ```shell\n    # For Linux or macOS:\n    source .venv/bin/activate\n\n    # For Windows:\n    .venv\\Scripts\\activate\n    ```\n\n5.  Install dependencies:\n\n    ```shell\n    make install\n    ```\n\n6.  To run the bot, use the command:\n\n    ```shell\n    make run\n    ```\n⠀\n### 📦 Using Docker\n⠀\n1.  Clone the repository and navigate into the project directory:\n\n    ```shell\n    git clone https://github.com/MrConsoleka/aiogram-bot-template.git\n    cd aiogram-bot-template\n    ```\n\n2.  Build the Docker Image:\n\n    ```shell\n    make docker-build\n    ```\n\n3.  Run the Project with Docker Compose:\n\n    ```shell\n    make docker-up\n    ```\n\n4.  Verify Bot is Running (Optional):\n\n    ```shell\n    make docker-logs\n    ```\n    or\n    ```shell\n    make docker-logs SERVICE=bot\n    ```\n\n5.  Stop the Project:\n\n    ```shell\n    make docker-down\n    ```\n\n⠀\n## 🗄️ Migrations\n⠀\n\nCreate and apply migrations with Alembic:\n\n```shell\nmake migration MESSAGE=\"create users\"\nuv run alembic upgrade head\n```\n\n⠀\n## 🧪 Testing\n⠀\n\nRun tests locally:\n\n```shell\nuv run pytest tests/\n```\n\n⠀\n## 🧰 Pre-commit\n⠀\n\n```shell\npre-commit install\npre-commit run --all-files\n```\n\n⠀\n## 🧩 Development Services\n⠀\n\n```shell\nmake dev-up\nmake dev-down\n```\n\n⠀\n## 📋 Todo List\n⠀\n\n- [x] touch the grass\n- [x] Alembic\n- [x] Aiogram-dialog\n- [x] .github/workflows\n\n⠀\n## 🗃️ Stack of Technologies\n⠀\n\n*   [aiogram-3x](https://github.com/aiogram/aiogram) - Asynchronous framework for the Telegram Bot API.\n*   [aiogram-dialog](https://github.com/aiogram/aiogram-dialog) - Dialog manager for building interactive flows.\n*   [dishka](https://github.com/arslnk/dishka) - Dependency injection container.\n*   [fastapi](https://github.com/tiangolo/fastapi) \u0026 [uvicorn](https://github.com/encode/uvicorn) - Webhook server stack.\n*   [pydantic](https://github.com/pydantic/pydantic) \u0026 [pydantic-settings](https://github.com/pydantic/pydantic-settings) - Data validation and configuration management.\n*   [postgresql](https://github.com/postgres/postgres) with [sqlalchemy](https://github.com/sqlalchemy/sqlalchemy) and [asyncpg](https://github.com/MagicStack/asyncpg?tab=readme-ov-file) - Database layer.\n*   [redis](https://redis.io/) - In-memory data store for FSM and caching.\n*   [loguru](https://github.com/Delgan/loguru) - Logging library.\n*   [prometheus-client](https://github.com/prometheus/client_python) - Metrics exporter (optional).\n*   [cachetools](https://github.com/tkem/cachetools) \u0026 [fluentogram](https://github.com/Arustinal/fluentogram) - Caching and localization helpers.\n*   [Ruff](https://github.com/astral-sh/ruff), [Mypy](https://github.com/python/mypy), [Pre-commit](https://github.com/pre-commit/pre-commit), [Isort](https://github.com/pycqa/isort), [Black](https://github.com/psf/black) - Code quality and formatting tools.\n\n⠀\n## 💼 Credits\n⠀\n\n-   [aiogram_template](https://github.com/Lems0n/aiogram_template) - Inspired by Abdullah's project, many thanks to him \u003c3\n\n⠀\n## 👤 Author of Aiogram Template Bot\n⠀\n**© Roman Alekseev**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrconsoleka%2Faiogram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrconsoleka%2Faiogram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrconsoleka%2Faiogram-bot-template/lists"}