Telegram bot and REST API for convenient control of your expenses and obtaining convenient statistics on spending.
- 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;
- 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.
Ilya Malashenko (github: melax08, telegram: @ScreamOFF)
- Python 3.11;
- Docker (19.03.0+) with docker compose for easy run.
Via docker
Clone the repo and change directory to it:
git clone https://github.com/melax08/cheapskate.git && cd cheapskateCreate an .env file in the src directory and add the necessary environment variables to it (check src/.env.example for necessary variables.)
mv src/.env.example src/.envvi src/.envRun docker compose to create docker containers:
docker compose up -dor
docker-compose up -dBot 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/utils/constants.py and src/utils/configs.py.
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.
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:appDocumentation will be available on URL: http://127.0.0.1:8000/docs
Before starting development and creating new commits, apply git hooks by running the command:
pre-commit installNow, when creating a new commit, the following will be automatically launched:
- Ruff linter;
- Ruff formatter;
- Pytest;
- Poetry check;
- check-yaml, end-of-file-fixer, trailing-whitespace.
You can manage the pre-commit hooks in a file: .pre-commit-config.yaml
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent