# kira-1011/bill-reminder-bot architecture

> Architecture diagram of the GitHub repository kira-1011/bill-reminder-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kira-1011/bill-reminder-bot
- Repository: https://github.com/kira-1011/bill-reminder-bot

## Overview

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: [`src/bot/bot.py`](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/bot.py) (Bot app), [`src/bot/services/payments.py`](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/services/payments.py) (Payments svc), [`src/bot/main.py`](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/main.py) (App bootstrap), [`src/bot/notifier.py`](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/notifier.py) (Notifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_entry["main.py<br/>entrypoint<br/>[main.py]"]
  node_app_bootstrap["App bootstrap<br/>startup<br/>[main.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_scheduler["Scheduler<br/>job runner<br/>[scheduler.py]"]
  node_notifier["Notifier<br/>reminder engine<br/>[notifier.py]"]
end

subgraph group_telegram["Telegram"]
  node_bot_factory["Bot app<br/>telegram app<br/>[bot.py]"]
  node_start_handler["Start<br/>handler<br/>[start.py]"]
  node_bills_handler["Bills UI<br/>handler<br/>[bills.py]"]
  node_payments_handler["Payments UI<br/>handler<br/>[payments.py]"]
  node_history_handler["History UI<br/>handler<br/>[history.py]"]
  node_errors_handler["Errors<br/>handler<br/>[errors.py]"]
  node_channel_base["Channel API<br/>abstraction<br/>[base.py]"]
  node_channel_telegram["Telegram ch.<br/>transport<br/>[telegram.py]"]
end

subgraph group_domain["Domain"]
  node_bills_service["Bills svc<br/>domain service<br/>[bills.py]"]
  node_payments_service["Payments svc<br/>domain service<br/>[payments.py]"]
  node_utils["Utils<br/>helpers<br/>[utils.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_connection[("DB conn<br/>async sqlalchemy<br/>[connection.py]")]
  node_db_models[("DB models<br/>orm schema<br/>[models.py]")]
  node_migrations["Migrations<br/>schema ops<br/>[env.py]"]
end

subgraph group_ops["Ops"]
end

node_main_entry -->|"starts"| node_app_bootstrap
node_app_bootstrap -->|"loads"| node_config
node_app_bootstrap -->|"connects"| node_db_connection
node_app_bootstrap -->|"applies"| node_migrations
node_app_bootstrap -->|"builds"| node_bot_factory
node_bot_factory -->|"registers"| node_start_handler
node_bot_factory -->|"registers"| node_bills_handler
node_bot_factory -->|"registers"| node_payments_handler
node_bot_factory -->|"registers"| node_history_handler
node_bot_factory -->|"registers"| node_errors_handler
node_start_handler -->|"delegates"| node_bills_service
node_bills_handler -->|"delegates"| node_bills_service
node_payments_handler -->|"delegates"| node_payments_service
node_history_handler -->|"reads"| node_payments_service
node_bills_service -->|"uses"| node_db_connection
node_payments_service -->|"uses"| node_db_connection
node_bills_service -->|"maps to"| node_db_models
node_payments_service -->|"maps to"| node_db_models
node_scheduler -->|"triggers"| node_notifier
node_notifier -->|"queries"| node_payments_service
node_notifier -->|"targets"| node_channel_base
node_channel_telegram -->|"implements"| node_channel_base
node_notifier -->|"uses"| node_channel_telegram
node_notifier -->|"dedupes via"| node_db_connection
node_bills_service -->|"uses"| node_utils
node_payments_service -->|"uses"| node_utils

click node_main_entry "https://github.com/kira-1011/bill-reminder-bot/blob/main/main.py"
click node_app_bootstrap "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/main.py"
click node_bot_factory "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/bot.py"
click node_config "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/config.py"
click node_start_handler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/start.py"
click node_bills_handler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/bills.py"
click node_payments_handler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/payments.py"
click node_history_handler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/history.py"
click node_errors_handler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/errors.py"
click node_bills_service "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/services/bills.py"
click node_payments_service "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/services/payments.py"
click node_scheduler "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/scheduler.py"
click node_notifier "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/notifier.py"
click node_channel_base "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/channels/base.py"
click node_channel_telegram "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/channels/telegram.py"
click node_db_connection "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/db/connection.py"
click node_db_models "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/db/models.py"
click node_utils "https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/utils.py"
click node_migrations "https://github.com/kira-1011/bill-reminder-bot/blob/main/migrations/env.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_entry,node_app_bootstrap,node_config,node_scheduler,node_notifier toneBlue
class node_bot_factory,node_start_handler,node_bills_handler,node_payments_handler,node_history_handler,node_errors_handler,node_channel_base,node_channel_telegram toneAmber
class node_bills_service,node_payments_service,node_utils toneMint
class node_db_connection,node_db_models,node_migrations toneRose
```

## Components

### Runtime

Async service startup, polling, and scheduled reminders

- [main.py](https://github.com/kira-1011/bill-reminder-bot/blob/main/main.py): entrypoint · Process entry that starts the bot service · `main.py`
- [App bootstrap](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/main.py): startup · Loads config, builds the app, starts polling · `src/bot/main.py`
- [Config](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/config.py): settings · Environment-driven runtime configuration · `src/bot/config.py`
- [Scheduler](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/scheduler.py): job runner · Daily reminder trigger at configured time · `src/bot/scheduler.py`
- [Notifier](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/notifier.py): reminder engine · Finds due bills and sends reminders · `src/bot/notifier.py`

### Telegram

Update handlers and Telegram transport

- [Bot app](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/bot.py): telegram app · Constructs the Telegram application and wiring · `src/bot/bot.py`
- [Start](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/start.py): handler · Registers users and shows commands · `src/bot/handlers/start.py`
- [Bills UI](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/bills.py): handler · Bill commands and conversation flows · `src/bot/handlers/bills.py`
- [Payments UI](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/payments.py): handler · Payment commands and cycle updates · `src/bot/handlers/payments.py`
- [History UI](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/history.py): handler · Payment history response formatting · `src/bot/handlers/history.py`
- [Errors](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/handlers/errors.py): handler · Central Telegram error handling · `src/bot/handlers/errors.py`
- [Channel API](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/channels/base.py): abstraction · Generic notification channel contract · `src/bot/channels/base.py`
- [Telegram ch.](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/channels/telegram.py): transport · Telegram implementation of reminder delivery · `src/bot/channels/telegram.py`

### Domain

Business logic and shared utilities

- [Bills svc](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/services/bills.py): domain service · User registration, bill CRUD, listing · `src/bot/services/bills.py`
- [Payments svc](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/services/payments.py): domain service · Cycle tracking, eligibility, history · `src/bot/services/payments.py`
- [Utils](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/utils.py): helpers · Pure date and formatting helpers · `src/bot/utils.py`

### Persistence

Database connection, models, and migrations

- [DB conn](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/db/connection.py): async sqlalchemy · Async engine and session setup · `src/bot/db/connection.py`
- [DB models](https://github.com/kira-1011/bill-reminder-bot/blob/main/src/bot/db/models.py): orm schema · Users, bills, payments, reminder log · `src/bot/db/models.py`
- [Migrations](https://github.com/kira-1011/bill-reminder-bot/blob/main/migrations/env.py): schema ops · Alembic environment and versioned schema · `migrations/env.py`

## Connections

- 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
