Electronic lab-submission queue in Telegram

The task

Before lab submissions or exams, a group usually keeps a sign-up list on paper or in a chat. Someone signs up and does not come, someone loses their place, and the lecturer cannot tell who has already submitted. The group leader spends time on manual corrections and reminders.

The group needs a queue that behaves like a system, not like a conversation. The group leader creates an event, students of the group sign up themselves, and the bot keeps the order, calls the next person and marks no-shows. The lecturer needs a ready list in a convenient format.

The solution

QueueBot is a Telegram bot for signing students up to electronic queues for submitting work and passing exams. What is implemented:

• registration with a shared invite code, then full name and group number; name uniqueness is checked within the group;
• three roles: student, group leader, administrator; blocked users are not allowed into the menu;
• several study groups: students see only their own group's queues;
• the queue itself: sign up, leave, skip a turn, rejoin at the end, view the queue, a “My status” screen;
• an “I'm here!” check-in when the event starts, and marking of no-shows;
• smart notifications when no more than three people remain ahead of a student;
• step-by-step queue creation by the group leader: subject, date, time, number of lecturers, confirmation; cancel with /cancel;
• manual order control: move up, move down, remove; announcements to the group as text or a photo;
• export of the queue to Excel;
• administrator broadcasts to everyone or to one group, with counters of delivered and blocked messages;
• a hidden /version command for the main administrator only.

How it works

Roles through middleware in aiogram

Middleware in aiogram 3 is code that runs before every handler. Here it reads the user's role from the database and injects it into the request, so a student physically never sees the group leader's menu and a blocked user does not reach the menu at all. The main administrator is set by a separate setting and grants rights to others with the /admin_add command. There is also protection against rapid tapping: no more than one request per 0.5 seconds per user.

Dialogs on a finite-state machine (FSM)

Registration and queue creation run step by step. An FSM (finite-state machine: the bot remembers which step a dialog is on) drives them. States are stored in process memory, so unfinished dialogs are lost on restart.

Scheduled check-in: APScheduler

Background jobs are run by APScheduler. Every minute the bot checks whether any events have started (a window of plus or minus two minutes) and sends the check-in. Every five minutes the check-in timeout fires: those who have not confirmed their presence are marked as no-shows. Every two minutes the smart notifications for events already in progress are checked.

Smart notifications about the approaching turn

When no more than three people remain ahead of a student, the bot sends a notification. It is not repeated while the student stays at the same position. The next person in line receives a separate message with “Ready to go” and “Skip” buttons.

Exporting the queue to Excel

The export module builds an .xlsx file with the openpyxl library. The group leader exports the list with a button, and the lecturer receives a table with the sign-up order and statuses.

Data: async SQLAlchemy and PostgreSQL

The database is PostgreSQL 15, accessed through SQLAlchemy 2.0 in async mode with the asyncpg driver. The main entities are user, subject, event and queue entry. Tables are created automatically on start. The bot and the database run through Docker Compose, and the containers' time zone is set explicitly, so the time in logs, check-ins and notifications matches Moscow time. Log files are rotated.

Results

• The queue is stored in a database rather than in a chat, and students see only their own group's queues.
• The bot sends the check-in, calls the next person and marks no-shows on its own.
• The group leader can adjust the order manually when needed; the administrator manages users and groups and sends broadcasts.
• The lecturer gets the queue as an Excel export.
• The repository has no automated tests; acceptance is manual.

Technologies and why

• Python 3.11 and aiogram 3 — an asynchronous Telegram bot: menus, roles, a finite-state machine for dialogs.
• SQLAlchemy 2.0 (async) and asyncpg — database access without blocking the bot.
• PostgreSQL 15 — storage for users, subjects, events and queue entries.
• APScheduler — check-in, no-show timeout and smart notifications on a schedule.
• openpyxl — exporting the queue to an Excel file.
• Docker Compose — starting the bot and the database with one command.

Status

Version 1.0.1 of 30 September 2026. The queue-bot repository is declared the only current one; it grew out of the earlier ocheredyV2 repository (version 2.1.0, February 2026) and botocheredy, which are no longer developed and have been archived. Known limitations from the README: dialog states and throttling are kept in memory, the bot is designed to run as a single instance, the schema is created on start without migrations, and access is protected by one shared invite code. Other details about the client are not disclosed.