Loyalty card for a gaming club in Telegram

The task

A gaming club ran its loyalty program on paper cards. Paper yields no numbers: how many players there are, how often they come, who is due a reward and what each staff member has credited.

The club needs a digital replacement: the administrator scans the client's QR code and credits a visit with one tap, the bot itself tracks when a reward is due (every sixth night or a free hookah) and keeps a log of staff actions. The owners need statistics and a daily copy of the database.

The solution

A Telegram bot replaces paper cards with a digital loyalty system: visit tracking (“nights”), reward issuing, a player database and a staff action log. What is implemented.

For the client:

• registration with the /start command;
• “My card (QR)”: the night balance, a six-cell progress bar, the reward status and a personal QR code;
• a notification when a reward becomes available: a free night or a hookah.

For the administrator:

• opening a client's profile from the QR code; the bot refuses everyone else;
• player search by phone number, and a list of all players with nickname, phone, nights and rewards spent;
• profile buttons: “Add night”, and when a reward is available, “Redeem: FREE NIGHT” and “Redeem: HOOKAH”;
• protection against inflation: a 70-second pause between credits and a ban on crediting yourself.

For the main administrator:

• club statistics: players, admins, total nights, rewards issued;
• a log of the last 30 actions;
• admin list management with the /add_admin and /del_admin commands;
• several main administrators, a daily database copy and a hidden /version command.

How it works

The client's QR card: qrcode and Pillow

The qrcode and Pillow libraries produce the QR image. The code contains a link that opens the bot with a scan_<client number> parameter. When the administrator scans the QR with the phone camera, Telegram opens the bot with exactly that parameter and the bot shows the client's profile. For other users the link gives nothing: the bot refuses.

The reward rule: every sixth night

The threshold is set by a constant: six nights. When the counter reaches six, the client is flagged as having a reward available and gets a notification. Redeeming reduces the balance by six and increases the counter of rewards spent. The reward type, night or hookah, is written to the log.

Anti-fraud: a pause and no crediting yourself

Abuse protection has two layers. First, 70 seconds must pass between credits from one administrator. Second, a regular administrator cannot credit a night to themselves. All credits and redemptions (ADD_NIGHT, SPENT_NIGHT, SPENT_HOOKAH) are written to a log that the main administrator views from the bot.

SQLite and aiosqlite: a database with no separate server

SQLite is a database in a single file and needs no separate server. The aiosqlite driver works with it asynchronously, so queries do not block the bot. The tables for players, administrators and the log are created on first start. For a small club this is enough: a backup is simply a file.

Three access levels: client, administrator, main administrator

Rights are checked against the administrator list in the database and the main administrator IDs from the settings. A client sees only their own card. An administrator opens profiles by QR or by phone number, credits nights, redeems rewards and views the player list; regular administrators have access to that list too. The main administrator additionally sees the statistics and the log and manages the set of administrators. A user without rights who opens a QR link gets a refusal.

Daily database copy

A background job sends the database file to all main administrators in Telegram once a day. There can be several main administrators: their IDs are listed, separated by commas, in an environment setting.

Results

• Paper cards are replaced by a QR card in Telegram: the client needs only a phone.
• The reward arrives automatically on the sixth night, and the client gets a notification.
• Crediting takes one tap, limited by a 70-second pause and a ban on crediting yourself.
• All staff actions are logged, and club statistics are available to the main administrator.
• A daily copy of the database reaches the main administrators as a file.
• The repository has no automated tests; acceptance is manual.

Technologies and why

• Python 3.10+ and aiogram 3 — an asynchronous Telegram bot with menus, roles and dialog states.
• SQLite and aiosqlite — storing players, administrators and the log in one file.
• qrcode and Pillow — generating the client's personal QR code.
• python-dotenv — the bot token and main administrator IDs from the environment.

Status

Version 2.2.1 of 11 January 2026. Since then the repository has gained a version constant, the hidden /version command and documentation; these changes are not yet cut as a release. Known limitations from the README: the pause between credits and dialog states are kept in memory and reset on restart; the reward type is recorded only in the log; the check that a reward is available is done at the button level, not in the database; there are no Docker files or automated tests; time in the database and log is stored in UTC. Other details about the client are not disclosed.