Birthday bot: reminders and a gift budget

The task

Birthdays of loved ones are easy to forget, and gifts cost money that is better set aside in advance. Usually the dates live in one person's head or in scattered notes, and nobody adds up the gift budget: the expenses hit all in one month.

What is needed is a shared list that friends and family fill in themselves, and a clear calculation for the one person who takes care of it. The administrator needs reminders in advance rather than on the day, and a number: how much to set aside for the coming months.

The solution

The birthday bot is the studio's own product: a Telegram bot that collects dates from any users, sends the administrator reminders and calculates a gift budget. What is implemented:

• step-by-step entry creation with the /add command: name, a date as DD.MM or DD.MM.YYYY (the year is optional), a budget and a note;
• a check that the date exists, including the number of days in the month;
• /list: all entries ordered by how soon the date is, with age (if a year is given), budget and note, with “Budget” and “Delete” buttons under each;
• /calendar: an interactive month calendar with birthdays marked and month navigation;
• /budget, for the administrator only: totals for 30, 90 and 365 days, a month-by-month breakdown for a year ahead and a grand total;
• a daily scheduled check and reminders to the administrator a configurable number of days ahead;
• /cancel to abort a dialog, and a hidden /version command for the administrator;
• Docker deployment with the database stored on the host's disk.

How it works

Step-by-step entry on an FSM in aiogram

An entry is created through a four-step dialog. It runs on an FSM (finite-state machine: the bot remembers which step a dialog with a particular person is on). The bot accepts a date with or without a year, checks that it exists, and the budget and note can be skipped with a “-”. Dialog states are kept in memory, so an unfinished dialog starts over after a bot restart.

Daily reminders: APScheduler and a cron schedule

APScheduler is a task scheduling library. Once a day at a set time (9:00 Moscow time by default) it runs a check: if a date is 14, 7, 3 or 1 days away, or is today, the administrator gets a reminder. The list of days is set through an environment variable, where 0 means the day itself. The schedule's time zone is configured separately.

The gift budget by month

Each entry can carry its own budget. The /budget command adds up the budgets of dates that fall within a 30-, 90- or 365-day window (the window is switched with buttons) and spreads the total across the months of the coming year. The breakdown shows the “expensive” months at once, when the most will go on gifts.

A calendar on inline buttons

The calendar is built from inline buttons right inside the message. Days with birthdays are marked with a cake icon, you can page through months, and tapping a number shows whose birthday it is. A 29 February birthday is marked on 1 March in a non-leap year.

SQLite in Docker: data survives a rebuild

SQLite is a database in a single file with no separate server. In Docker the database file is placed on the host's disk (a volume), so it survives a container rebuild. The container publishes no ports because the bot polls Telegram itself (long polling), has a 256 MB memory limit and log rotation. A backup is a copy of the file, preferably taken while the container is stopped.

Permissions: who can do what

Any user of the bot can add entries. The budget can be changed or an entry deleted by the administrator or by whoever added it. Reminders and /budget are seen only by the administrator, who is identified by an ID from the settings.

Results

• Birthdays are collected by friends and family, not by a single person.
• The administrator gets reminders in advance rather than on the day.
• The gift budget is visible in numbers for 30, 90 and 365 days, broken down by month.
• Data is kept in one file and survives a container restart.
• The repository has no automated tests; acceptance is manual.

Technologies and why

• Python and aiogram 3 — an asynchronous Telegram bot: commands, dialogs, inline buttons.
• SQLite and aiosqlite — storing entries in one file, with async access that does not block the bot.
• APScheduler — the daily check and reminder delivery on a schedule.
• python-dotenv — the bot token, the administrator ID and reminder settings from the environment.
• Docker Compose — running on a server with the database on the host's disk and a Moscow time zone in the container.

Status

Version 1.0.0 of 30 September 2026. The version is printed to the log on every start, and there is a hidden /version command. Known limitations: only the administrator receives reminders; the name, date and note cannot be edited after adding (only the budget and deletion); the list has to be reopened after deleting an entry; there are no schema migrations.