Jessy is a template for building Telegram bots using the Aiogram framework, with a focus on clean architecture, modularity, and maintainability. It leverages async programming, SQLAlchemy ORM, Alembic migrations, and Docker for deployment. The project is structured to separate concerns such as handlers, middlewares, database, and configuration.
jessy/
βββ app/ # Main application code
β βββ bot.py # Bot entry point and dispatcher setup
β βββ buttons/ # Telegram keyboard/button definitions
β βββ config/ # Configuration and environment loading
β βββ database/ # Database models, access, and admin/user logic
β βββ handlers/ # Message handlers for users and admins
β βββ middlewares/ # Custom aiogram middlewares
β βββ utils/ # Filters, states, and utility code
βββ migrations/ # Alembic migration scripts
βββ logs/ # Log files (created at runtime)
βββ docs/ # Documentation (this file, etc.)
βββ main.py # Simple hello-world entry (for testing)
βββ run.sh # Shell script to run the bot
βββ requirements.txt # Python dependencies
βββ pyproject.toml # Project metadata and dependencies
βββ Dockerfile # Docker build instructions
βββ docker-compose.yml # Docker Compose setup for bot and DB
βββ alembic.ini # Alembic configuration
βββ README.md # Main project documentation
βββ LICENSE # License file
- Handlers are split into
usersandadminsfor clarity and access control. - Middlewares encapsulate cross-cutting concerns (e.g., anti-flood, user tracking).
- Database logic is separated into schema, user, and admin modules.
- Buttons and utils are isolated for reusability.
- All I/O (DB, bot polling) is async for scalability.
- Type hints are used throughout for clarity and tooling support.
- All secrets and environment variables are loaded via
.envandpython-dotenv. - No secrets are hardcoded; use
os.getenvinconfig.py.
- SQLAlchemy ORM is used for models and async DB access.
- Alembic is used for migrations, with scripts in
migrations/. - All DB access is via async sessions and context managers.
- Loguru is used for structured logging to files in
logs/. - Errors are logged and handled gracefully; the bot exits on fatal errors.
- Handlers and middlewares are designed to be easily testable and extendable.
- New features should be added as new routers, middlewares, or utility modules.
- Dockerfile and docker-compose.yml provide reproducible environments.
- Alembic migrations are run automatically on container startup.
- Follows PEP8 and modern Python best practices.
- Use of docstrings for all public functions and classes.
- Consistent naming:
snake_casefor functions/variables,CamelCasefor classes.
- app/bot.py: Main entry, sets up dispatcher, routers, middlewares, and starts polling.
- app/handlers/: Contains message handlers for users and admins, organized by role.
- app/middlewares/: Custom aiogram middlewares (e.g., anti-flood, user tracking).
- app/database/: Async DB setup, models, and user/admin logic.
- app/buttons/: Keyboard and button definitions for Telegram UI.
- app/utils/: Filters, FSM states, and other helpers.
- app/config/: Loads environment variables and bot settings.
- migrations/: Alembic migration scripts for DB schema changes.
- logs/: Log files (created at runtime).
- docs/: Project documentation.
- Add new handlers in
app/handlers/and register them inbot.py. - Add new middlewares in
app/middlewares/and include them in the dispatcher. - For new DB models, update
app/database/schema.pyand create a new Alembic migration. - Use environment variables for all secrets and configuration.
- Create a new handler in
app/handlers/users/orapp/handlers/admins/. - Register the handler in the corresponding router list in
__init__.py. - Import and include the router in
bot.py.
- Follow the code principles above.
- Write clear, modular, and well-documented code.
- Update documentation and tests when adding features.