Loading repository data…
MrConsoleka / repository
Template for building scalable Telegram bots with aiogram + Mini App (WebApp)
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
⠀
Aiogram Bot Template with Mini Apps — This template helps you quickly bootstrap Telegram bots with Mini Apps on the aiogram 3.x stack. It includes a ready project structure, command and message handlers, PostgreSQL/Redis integration, logging with loguru, internationalization, aiogram-dialog, dependency injection via dishka, webhook handling on FastAPI, plus a React Mini App frontend with secure authentication and REST API backend. The template is designed to remove routine setup and let you focus on your bot's logic and user experience.
⠀
⠀
Telegram Bot Foundation:
Mini Apps:
initDataSecurity Hardened:
DevOps Ready:
Selected from shared topics, language and repository description—not editorial ratings.
bodaue /
A template for building Telegram bots using aiogram 3.x and sqlalchemy 2.x
66/100 healthshox404 /
An Aiogram template is a structured boilerplate for building Telegram bots using the Aiogram framework in Python. It provides a predefined project structure and commonly used components to simplify and speed up bot development.
32/100 healthMrR4di0k4l /
⠀
⠀
/start - Start the bot/language - Change language/help - Help/profile - Open your Mini App profile/admin - Command for administrators/dialog - Demo dialog using aiogram-dialog/fsm - Demo finite state machine form⠀
⠀
This template includes a React Mini App for user profiles:
Try it: Send /profile to your bot!
⠀
⠀
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Telegram User │─────▶│ Your Bot │─────▶│ PostgreSQL │
│ (Mobile App) │ │ (aiogram 3.x) │ │ + Redis │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│ │
│ Opens Mini App │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ React Mini App │◀────▶│ FastAPI Backend │
│ (TypeScript) │ │ (/api/...) │
└──────────────────┘ └──────────────────┘
│ │
└────────▶ nginx ◀────────┘
(reverse proxy)
⠀
⠀
📁 aiogram-miniapp-template/
├── 📂 .github/ # CI/CD workflows, issue templates
├── 📂 docs/ # Documentation
├── 📂 migrations/ # Alembic database migrations
├── 📂 nginx/ # nginx reverse proxy configs
├── 📂 scripts/ # Helper scripts
├── 📂 source/ # Main Python source code
│ ├── 📂 api/ # FastAPI backend for Mini Apps
│ ├── 📂 config/ # Configuration
│ ├── 📂 database/ # Models, repositories, UoW
│ ├── 📂 schemas/ # Pydantic schemas for API
│ ├── 📂 services/ # Business logic
│ ├── 📂 telegram/ # Bot handlers, keyboards, filters
│ └── 📂 utils/ # Utilities
├── 📂 tests/ # Test suite
├── 📂 webapp/ # React Mini App frontend
│ ├── 📂 public/locales/ # i18n translations
│ └── 📂 src/ # React components, hooks, API client
├── docker-compose.yml
├── Dockerfile
├── webapp.Dockerfile
└── pyproject.toml
Full project structure is documented in docs/reference/project-structure.md.
⠀
⠀
📁 source/ - Main application source code.📁 source/api/ - FastAPI backend for Mini Apps (routes, middlewares, utils).📁 source/config/ - Application configuration settings.📁 source/constants/ - Project constants.📁 source/data/ - Data generated by the application (e.g., logs).📁 source/database/ - Database interaction logic (models, repositories, UoW).📁 source/schemas/ - Pydantic schemas for API request/response validation.📁 source/services/ - Business logic layer.📁 source/telegram/ - Bot components (handlers, keyboards, filters, middlewares, states, dialogs).📁 source/utils/ - Helper utilities (logger, i18n, validators).📁 webapp/ - React Mini App frontend with TypeScript.📁 webapp/src/ - React components, hooks, pages, API client.📁 webapp/public/locales/ - i18n translation files for Mini App.📁 nginx/ - nginx configuration for reverse proxy.📁 docs/ - Development and deployment documentation.📁 scripts/ - Helper scripts for development tasks.📁 tests/ - Test suite.⠀
⠀
Full documentation is available in the docs/ folder:
Getting Started:
Bot Development:
Mini Apps Development:
Deployment:
Reference:
⠀
⠀
Backend & Bot (.env):
| Environment Variable Name | Description |
|---|---|
| ENVIRONMENT | Application environment (development, test, production). |
| TG__WEBHOOK_USE | Boolean value (True/False) indicating whether to use webhooks (True) or long polling (False). |
| TG__WEBHOOK_PATH | Path for Telegram to send webhook updates (appended to WEBHOOK__URL). |
| TG__BOT_TOKEN | Your Telegram bot token, obtained from @BotFather in Telegram. |
| TG__ADMIN_IDS | List of Telegram user IDs (JSON list or comma-separated) who will have administrator rights in the bot. |
| WEBHOOK__URL | Public URL where Telegram will send updates if webhooks are enabled. |
| WEBHOOK__HOST | Host or IP address where the webhook server will listen for incoming connections (usually 0.0.0.0). |
| WEBHOOK__PORT | Port on which the webhook server will listen for incoming connections. |
| WEBHOOK__SECRET | Secret token that Telegram includes in webhook request headers to verify authenticity. |
| DB__HOST | Database server host. |
| DB__PORT | Port for connecting to the database. |
| DB__USER | Username for database authentication. |
| DB__PASSWORD | Password for database authentication. |
| DB__NAME | Name of the database to connect to. |
| REDIS__HOST | Redis server host used for FSM and/or caching. |
| REDIS__PORT | Port for connecting to the Redis server. |
| REDIS__USER | Username for Redis authentication (if used). |
| REDIS__PASSWORD | Password for Redis authentication (if used). |
| REDIS__DB | Redis database index to use (a number from 0 to 15, default is 0). |
| API__HOST | FastAPI host for Mini Apps API (usually 0.0.0.0). |
| API__PORT | FastAPI port (default 8000). |
| API__DEBUG | Debug mode for API (true/false). |
| WEBAPP__URL | Public URL where Mini App is hosted (e.g., https://your-domain.com). |
Mini App Frontend (webapp/.env):
| Environment Variable Name | Description |
|---|---|
| VITE_API_URL | Base URL for the Mini App API (default /api). |
Note: docker-compose maps WEBHOOK__PORT to the host (defaults to 8080 if not set).
⠀
⠀
⠀
Clone the repository and navigate into the project directory:
git clone https://github.com/MrConsoleka/aiogram-miniapp-template.git
cd aiogram-miniapp-template
Configure environment variables:
cp .env.example .env
cp webapp/.env.example webapp/.env
# Edit .env and webapp/.env with your settings
Start all services with Docker Compose:
docker compose up -d
⠀
⠀
Clone the repository and navigate into the project directory:
git clone https://github.com/MrConsoleka/aiogram-miniapp-template.git
cd aiogram-miniapp-template
Ensure you have uv installed. If not, you can install it using pip:
pip install uv
Create a virtual environment:
make venv
Activate the virtual environment:
# For Linux or macOS:
source .venv/bin/activate
# For Windows:
.venv\Scripts\activate
Install dependencies:
make install
Configure environment variables:
cp .env.example .env
cp webapp/.env.example webapp/.env
# Edit .env and webapp/.env with your settings
Run the bot:
make run
(Optional) Run Mini App frontend separately:
# In a separate terminal
cd webapp
npm install
npm run dev
If r
A clean, production-ready template for building Telegram bots using Aiogram 2 and Tortoise ORM, with full Docker support.