Project / Python
Telegram Expense Splitting Bot
A self-hosted group expense tracker with flexible splits and receipt OCR
Overview
A Telegram bot that keeps shared expenses inside the group chat. It supports guided and command-based expense entry, multiple split and payer models, balances, settlements, reporting, and receipt-assisted workflows backed by PostgreSQL.
What it does
- 01Equal, exact-amount, percentage, and share-based splits with multiple payers
- 02Interactive add and edit flows alongside concise text commands
- 03Balances, debt simplification, settlements, undo safeguards, and expense history
- 04Weekly, monthly, yearly, and category summaries with Excel export
- 05Receipt attachment and OCR-first expense creation through a separate RapidOCR worker
- 06Dockerized bot, worker, and PostgreSQL deployment validated for Raspberry Pi 5
Build notes
- backend
- Python, python-telegram-bot, asyncio, RapidOCR
- database
- PostgreSQL, psycopg
- tools
- Docker, pytest, Ruff, Raspberry Pi
Hard part
The hardest part was making money updates and OCR suggestions safe without making the chat workflow cumbersome. Amounts use integer minor units and deterministic rounding, PostgreSQL transactions protect related changes, and OCR never creates or changes an expense without confirmation. The worker uses a durable PostgreSQL queue with retries, stale-job recovery, and concurrent claim protection.
Next pass
Before wider use, I would calibrate OCR against a broader set of real receipts and add more live Telegram integration coverage. Shared session storage would only become worthwhile if the bot grows beyond one application replica or temporary interactions need to survive restarts.