cheapskate - telegram bot and API for financial control

Information

Description

Telegram bot and REST API for convenient control of your expenses and obtaining convenient statistics on spending.

Features

• REST API with swagger documentation, allows to connect backend to your custom interface like mobile apps, sites, etc;
• Telegram bot that provides a convenient interface for managing expenses;
• Ability to add categories of expenses, which will be displayed as a keyboard in the bot when adding expenses;
• Ability to add and remove expenses by category from the list of previously added ones;
• Currencies system (add currency, show expenses by currencies and categories);
• Settings to set default currency and month budget;
• Various options to get statistics on spending (today's spending, remaining money for the month, statistics by month and years, etc.);
• Authentication system;
• Error handling and logging;
• Asynchronous interaction between telegram bot and API.

Author

Ilya Malashenko (github: melax08, telegram: @ScreamOFF)

System requirements

• Python 3.13;
• Docker (20.10+) with docker compose;
• uv.

Tech stack

Installation and start

Local run (Docker + local services)

1. Clone the repo and change directory to it:

git clone https://github.com/melax08/cheapskate.git && cd cheapskate

2. Create an .env file in the src directory and add the necessary environment variables to it (check src/.env.example for necessary variables.)

cp src/.env.example src/.env

vi src/.env

3. Install dependencies via uv:

uv sync

4. Run database and caching server via docker compose:

docker compose up -d

5. Change directory to the application source directory:

cd src

6. Apply database migrations and initial instances:

uv run alembic -c backend/alembic.ini upgrade head
uv run python3 -m backend.db_init

7. Run a bot and an API in the different terminal tabs:

# First tab
uv run fastapi dev api.py

# Second tab
uv run python3 -m bot

Production run (Docker)

1. Clone the repo and change directory to it:

git clone https://github.com/melax08/cheapskate.git && cd cheapskate

2. Create an .env file in the src directory and add the necessary environment variables to it (check src/.env.example for necessary variables.)

cp src/.env.example src/.env

vi src/.env

3. Run docker compose to create docker containers and run services:

docker compose -f infra/docker-compose-prod.yml up -d

Settings and documentation

Settings

Bot constants available in directory: src/bot/constants/

API constants and some bot constants you can configure in .env file (see example in src/.env.example file).

Common constants for bot and API you can find in src/configs/constants.py.

Telegram commands and usage

Only Telegram users whose IDs are listed in the ALLOWED_TELEGRAM_IDS (check the .env.example file for details) environment variable have access to the bot. If there is no ID in this environment variable, then all users have access to the bot (not recommended).

Create categories and expense management

First, you need to create spending categories so that you can add expenses to them in the future.

To do this, send the /add_category command to the bot and follow the instructions.

Once at least one category has been created, you can add expenses. To do this, send the bot the amount of money that was spent, and then select the category to which the spending belongs.

If an expense was added by mistake, or the wrong category was selected, you can click on the delete expense button.

Obtaining spending statistics

There are several commands that allow you to get a variety of spending statistics.

/money_left - shows statistics on spending for the current month, including statistics on spending categories and the balance of funds until the end of the month.

/today - shows the amount of money spent today, including information by spending category

/statistics - allows you to view spending statistics for a specific month of a specific year.

API documentation

If you run API locally by using uvicorn, you can get access to the swagger documentation of the API.

If you run API by command (before run this command, you need to install virtual environment for python3 and needed dependencies):

cd cheapskate/src && uvicorn api:app

Documentation will be available on URL: http://127.0.0.1:8000/docs

For developers

Before starting development and creating new commits, apply git hooks by running the command:

pre-commit install

Now, when creating a new commit, the following will be automatically launched:

• Ruff linter;
• Ruff formatter;
• Pytest;
• check-yaml, end-of-file-fixer, trailing-whitespace.

You can manage the pre-commit hooks in a file: .pre-commit-config.yaml