{"id":32719099,"url":"https://github.com/almaz122/aiogram-bot-template","last_synced_at":"2025-11-02T18:03:20.323Z","repository":{"id":318948672,"uuid":"1076997412","full_name":"Almaz122/aiogram-bot-template","owner":"Almaz122","description":"A Telegram bot template with built-in logging and a database, written using the aiogram library in Python 3.12","archived":false,"fork":false,"pushed_at":"2025-10-15T18:20:21.000Z","size":97,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-16T18:20:17.754Z","etag":null,"topics":["aiogram","aiogram-bot","aiogram-bot-template","async","asyncio","bot","python","python-3","python3","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Almaz122.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T16:20:14.000Z","updated_at":"2025-10-16T09:03:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"04ff83b4-70b3-43ec-86b1-c365ac0c8262","html_url":"https://github.com/Almaz122/aiogram-bot-template","commit_stats":null,"previous_names":["almaz122/aiogram-bot-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/Almaz122/aiogram-bot-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almaz122%2Faiogram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almaz122%2Faiogram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almaz122%2Faiogram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almaz122%2Faiogram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Almaz122","download_url":"https://codeload.github.com/Almaz122/aiogram-bot-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almaz122%2Faiogram-bot-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282332561,"owners_count":26652047,"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","status":"online","status_checked_at":"2025-11-02T02:00:06.609Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-bot","aiogram-bot-template","async","asyncio","bot","python","python-3","python3","telegram"],"created_at":"2025-11-02T18:02:32.084Z","updated_at":"2025-11-02T18:03:20.316Z","avatar_url":"https://github.com/Almaz122.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Aiogram 3 Bot Template\n\nThis is a template for telegram bots written in python using the `aiogram` framework\n\n\nYou can learn how to develop telegram bots using the `aiogram` framework in the following courses (in Russian):\n1. \u003ca href=\"https://stepik.org/course/120924/\"\u003eТелеграм-боты на Python и AIOgram\u003c/a\u003e\n2. \u003ca href=\"https://stepik.org/a/153850?utm_source=kmsint_github\"\u003eТелеграм-боты на Python: продвинутый уровень\u003c/a\u003e\n\n## About the template\n\n### Used technology\n* Python 3.12;\n* aiogram 3.x (Asynchronous Telegram Bot framework);\n* aiogram_dialog (GUI framework for telegram bot);\n* dynaconf (Configuration Management for Python);\n* taskiq (Async Distributed Task Manager);\n* fluentogram (Internationalization tool in the Fluent paradigm);\n* Docker and Docker Compose (containerization);\n* PostgreSQL (database);\n* NATS (queue and FSM storage);\n* Redis (cache, taskiq result backend);\n* Alembic (database migrations with raw SQL).\n\n### Structure\n\n```\n📁 aiogram_bot_template/\n├── 📁 alembic/\n│   ├── 📁 versinos/\n│   │   ├── 1541bb8a3f26_.py\n│   │   └── b20e5643d3bd_.py\n│   ├── env.py\n│   └── script.py.mako\n├── 📁 app/\n│   ├── 📁 bot/\n│   │   ├── 📁 dialogs/\n│   │   │   ├── 📁 flows/\n│   │   │   │   ├── 📁 settings/\n│   │   │   │   │   ├── dialogs.py\n│   │   │   │   │   ├── getters.py\n│   │   │   │   │   ├── handlers.py\n│   │   │   │   │   ├── keyboards.py\n│   │   │   │   │   └── states.py\n│   │   │   │   ├── 📁 start/\n│   │   │   │   │   ├── dialogs.py\n│   │   │   │   │   ├── getters.py\n│   │   │   │   │   ├── handlers.py\n│   │   │   │   │   └── states.py\n│   │   │   │   └── __init__.py\n│   │   │   └── 📁 widgets/\n│   │   │       └── i18n.py\n│   │   ├── 📁 enums/\n│   │   │   ├── actions.py\n│   │   │   └── roles.py\n│   │   ├── 📁 filters/\n│   │   │   └── dialog_filters.py\n│   │   ├── 📁 handlers/\n│   │   │   ├── __init__.py\n│   │   │   ├── commands.py\n│   │   │   └── errors.py\n│   │   ├── 📁 i18n/\n│   │   │   └── translator_hub.py\n│   │   ├── 📁 keyboards/\n│   │   │   ├── links_kb.py\n│   │   │   └── menu_button.py\n│   │   ├── 📁 middlewares/\n│   │   │   ├── database.py\n│   │   │   ├── get_user.py\n│   │   │   ├── i18n.py\n│   │   │   └── shadow_ban.py\n│   │   ├── 📁 states/\n│   │   │   └── states.py\n│   │   ├── __init__.py\n│   │   └── bot.py\n│   ├── 📁 infrastructure/\n│   │   ├── 📁 cache/\n│   │   │   └── connect_to_redis.py\n│   │   ├── 📁 database/\n│   │   │   ├── 📁 connection/\n│   │   │   │   ├── base.py\n│   │   │   │   ├── connect_to_pg.py\n│   │   │   │   └── psycopg_connection.py\n│   │   │   ├── 📁 models/\n│   │   │   │   └── users.py\n│   │   │   ├── 📁 query/\n│   │   │   │   └── results.py\n│   │   │   ├── 📁 tables/\n│   │   │   │   ├── 📁 enums/\n│   │   │   │   │   ├── base.py\n│   │   │   │   │   └── users.py\n│   │   │   │   ├── base.py\n│   │   │   │   └── users.py\n│   │   │   ├── 📁 views/\n│   │   │   │   └── views.py\n│   │   │   └── db.py\n│   │   └── 📁 storage/\n│   │       ├── 📁 storage/\n│   │       │   └── nats_storage.py\n│   │       └── nats_connect.py\n│   └── 📁 services/\n│       ├── 📁 delay_service/\n│       │   ├── 📁 models/\n│       │   │   └── delayed_messages.py\n│       │   ├── consumer.py\n│       │   ├── publisher.py\n│       │   └── start_consumer.py\n│       └── 📁 scheduler/\n│           ├── taskiq_broker.py\n│           └── tasks.py\n├── 📁 config/\n│   ├── config.py\n│   └── settings.toml\n├── 📁 locales/\n│   ├── 📁 en/\n│   │   ├── 📁 LC_MESSAGES/\n│   │   │   └── txt.ftl\n│   │   └── 📁 static/\n│   └── 📁 ru/\n│       ├── 📁 LC_MESSAGES/\n│       │   └── txt.ftl\n│       └── 📁 static/\n├── 📁 nats_broker/\n│   ├── 📁 config/\n│   │   └── server.conf\n│   └── 📁 migrations/\n│       └── create_stream.py\n├── .env\n├── .env.example\n├── .gitignore\n├── alembic.ini\n├── docker-compose.example\n├── docker-compose.yml\n├── main.py\n├── pyproject.toml\n├── README.md\n└── uv.lock\n```\n\n## Installation\n\n1. Clone the repository to your local machine via HTTPS:\n\n```bash\ngit clone https://github.com/Almaz122/aiogram-bot-template.git\n```\nor via SSH:\n```bash\ngit clone git@github.com:Almaz122/aiogram-bot-template.git\n```\n\n2. Create a `docker-compose.yml` file in the root of the project and copy the code from the `docker-compose.example` file into it.\n\n3. Create a `.env` file in the root of the project and copy the code from the `.env.example` file into it. Replace the required secrets (BOT_TOKEN, ADMINS_CHAT, etc).\n\n4. Run `docker-compose.yml` with `docker compose up` command. You need docker and docker-compose installed on your local machine.\n\n5. Create a virtual environment in the project root and activate it.\n\n6. Install the required libraries in the virtual environment. With `pip`:\n```bash\npip install .\n```\nor if you use `poetry`:\n```bash\npoetry install --no-root\n```\n7. Write SQL code in the `upgrade` and `downgrade` functions to create a database schema. See example in file `alembic/versions/1541bb8a3f26_.py`.\n\n8. If required, create additional empty migrations with the command:\n```bash\nalembic revision\n```\nand fill them with SQL code.\n\n9. Apply database migrations using the command:\n```bash\nalembic upgrade head\n```\n\n10. Run `create_stream.py` to create NATS stream for delayed messages service:\n```bash\npython3 -m nats_broker.migrations.create_stream\n```\n\n11. If you want to use the Taskiq broker for background tasks as well as the Taskiq scheduler, add your tasks to the `tasks.py` module and start the worker first:\n```bash\ntaskiq worker app.services.scheduler.taskiq_broker:broker -fsd\n```\nand then the scheduler:\n```bash\ntaskiq scheduler app.services.scheduler.taskiq_broker:scheduler\n```\n\n12. Run `main.py` to check the functionality of the template.\n\n13. You can fill the template with the functionality you need.\n\n## Developer tools\n\nFor convenient interaction with nats-server you need to install nats cli tool. For macOS you can do this through the homebrew package manager. Run the commands:\n```bash\nbrew tap nats-io/nats-tools\nbrew install nats-io/nats-tools/nats\n```\nFor linux:\n```bash\ncurl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh\nsudo mv nats /usr/local/bin/\n```\nAfter this you can check the NATS version with the command:\n```bash\nnats --version\n```\n\n## TODO\n\n1. ?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmaz122%2Faiogram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falmaz122%2Faiogram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falmaz122%2Faiogram-bot-template/lists"}