How kira-1011/bill-reminder-bot works
1. What this repository is
- This is a Telegram reminder bot, not a web app.
- The runtime is a single async Python service that polls Telegram, persists state in PostgreSQL, and runs a scheduled daily reminder job.
2. Top-level execution path
- main.py starts the application in src/bot/main.py.
- Startup includes loading config, connecting to the database, applying Alembic migrations automatically, building the Telegram bot app, and starting polling.
- The same process also hosts the reminder scheduler, so there is no separate worker service.
3. Core runtime stack
- Telegram integration uses python-telegram-bot v22.
- Background timing uses APScheduler job queue.
- Persistence uses async SQLAlchemy 2.0 with asyncpg against PostgreSQL 17.
- Configuration is environment-driven through pydantic-settings.
4. Main architectural boundaries
- handlers/ is the Telegram-facing entry layer: command handlers and callback handlers.
- services/ contains business logic and database workflows.
- db/ contains SQLAlchemy engine/session setup and ORM models.
- utils.py holds pure date/format helpers with no external dependencies.
- notifier.py and scheduler.py orchestrate reminder sending and the daily reminder run.
5. Primary request/response flow
- A Telegram command or callback update arrives at a handler.
- The handler validates input and delegates to a service.
- The service reads/writes the database via async sessions.
- The handler formats the result back into Telegram messages or inline keyboards.
- This keeps Telegram-specific behavior separate from the domain rules.
6. Business domains
- services/bills.py handles user registration, bill creation, listing, and deletion.
- services/payments.py handles payment lifecycle, due-cycle tracking, reminder eligibility, and history queries.
- The important domain concepts are users, bills, payment cycles, and reminder logs.
7. Reminder subsystem
- scheduler.py triggers the daily reminder run at 09:00 in the configured timezone.
- notifier.py determines which bills are due for each user, formats reminder messages, and sends them through a channel abstraction.
- Reminder deduplication is enforced by reminder_log, so a given bill/due date/offset/channel combination is sent once per cycle.
8. Notification channel abstraction
- channels/base.py defines a generic channel contract.
- channels/telegram.py is the concrete implementation used by the bot.
- This creates a boundary between reminder logic and the transport used to deliver notifications, which would allow future non-Telegram channels without changing reminder rules.
9. Persistence model
- The database schema centers on users, bills, payments, and reminder_log.
- users map Telegram identities to internal IDs.
- bills store recurring bill metadata including due day and reminder offsets.
- payments record per-cycle status such as pending, paid, or missed.
- reminder_log is the idempotency layer for notifications.
10. User-facing features mapped to code
- /start registers the user and presents available commands.
- /addbill is a guided conversation to create a bill.
- /bills lists active bills.
- /delbill deletes via inline keyboard interaction.
- /paid marks the current cycle as paid.
- /history returns grouped payment history for the last six months.
11. Time and cycle logic
- Due dates are normalized around a user bill’s due_day constraint of 1–28.
- Reminder timing is offset-based: 7, 3, and 1 day before due by default.
- Payment records use a cycle_key pattern to separate monthly occurrences of the same bill.
12. Operational and deployment shape
- The repo is container-first: Dockerfile and docker-compose.yml run the bot plus PostgreSQL.
- Alembic migrations are part of startup, which means schema management is built into the service lifecycle.
- .env.example and config docs show that all runtime dependencies are externalized via environment variables.
13. Quality and validation
- Tests are isolated from external services by mocking AsyncSession; no live database or Telegram bot is required.
- Coverage focuses on pure utilities, bill/payment services, and notifier behavior.
- CI is lightweight and enforces linting/formatting with Ruff.
14. How to draw the architecture
- A good diagram would show: Telegram updates flowing into handlers, handlers calling services, services using the async DB layer, and responses flowing back to Telegram.
- Separately, show the scheduler invoking notifier logic on a daily cadence, with reminder delivery going through the channel abstraction and persistence-backed deduplication.
- The database is the shared system of record for users, bills, payments, and sent reminders.
Main entry points: bot.py Bot app · payments.py Payments svc · main.py App bootstrap · notifier.py Notifier
Components 19
Runtime
Async service startup, polling, and scheduled reminders
- main.py · Process entry that starts the bot service
main.py - App bootstrap · Loads config, builds the app, starts polling
src/bot/main.py - Config · Environment-driven runtime configuration
src/bot/config.py - Scheduler · Daily reminder trigger at configured time
src/bot/scheduler.py - Notifier · Finds due bills and sends reminders
src/bot/notifier.py
Telegram
Update handlers and Telegram transport
- Bot app · Constructs the Telegram application and wiring
src/bot/bot.py - Start · Registers users and shows commands
src/bot/handlers/start.py - Bills UI · Bill commands and conversation flows
src/bot/handlers/bills.py - Payments UI · Payment commands and cycle updates
src/bot/handlers/payments.py - History UI · Payment history response formatting
src/bot/handlers/history.py - Errors · Central Telegram error handling
src/bot/handlers/errors.py - Channel API · Generic notification channel contract
src/bot/channels/base.py - Telegram ch. · Telegram implementation of reminder delivery
src/bot/channels/telegram.py
Domain
Business logic and shared utilities
- Bills svc · User registration, bill CRUD, listing
src/bot/services/bills.py - Payments svc · Cycle tracking, eligibility, history
src/bot/services/payments.py - Utils · Pure date and formatting helpers
src/bot/utils.py
Persistence
Database connection, models, and migrations
- DB conn · Async engine and session setup
src/bot/db/connection.py - DB models · Users, bills, payments, reminder log
src/bot/db/models.py - Migrations · Alembic environment and versioned schema
migrations/env.py
Connections 26
- main.py → App bootstrap: starts · Launches the async service process
- App bootstrap → Config: loads · Reads environment-based settings
- App bootstrap → DB conn: connects · Initializes async database access
- App bootstrap → Migrations: applies · Runs schema migrations during startup
- App bootstrap → Bot app: builds · Assembles the Telegram application
- Bot app → Start: registers · Wires command handlers
- Bot app → Bills UI: registers · Wires bill conversations and callbacks
- Bot app → Payments UI: registers · Wires payment commands
- Bot app → History UI: registers · Wires history responses
- Bot app → Errors: registers · Adds centralized error handling
- Start → Bills svc: delegates · Creates or looks up users and bills
- Bills UI → Bills svc: delegates · Performs bill workflows
- Payments UI → Payments svc: delegates · Updates payment state and queries cycles
- History UI → Payments svc: reads · Fetches grouped payment history
- Bills svc → DB conn: uses · Opens async sessions for persistence
- Payments svc → DB conn: uses · Reads and writes cycle/payment records
- Bills svc → DB models: maps to · Persists user and bill records
- Payments svc → DB models: maps to · Persists payments and reminder state
- Scheduler → Notifier: triggers · Invokes the daily reminder run
- Notifier → Payments svc: queries · Checks due cycles and reminder eligibility
- Notifier → Channel API: targets · Sends through channel abstraction
- Telegram ch. → Channel API: implements · Concrete Telegram delivery channel
- Notifier → Telegram ch.: uses · Delivers reminder messages in Telegram
- Notifier → DB conn: dedupes via · Checks and records reminder log entries
- Bills svc → Utils: uses · Normalizes dates and formatting
- Payments svc → Utils: uses · Computes cycles and display values