-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Masudur Rahman <[email protected]>
- Loading branch information
1 parent
3532de2
commit 83085bc
Showing
9 changed files
with
350 additions
and
221 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,217 +4,152 @@ A Telegram Bot to track your expenses. | |
|
|
||
| ## Description | ||
|
|
||
| `Expense Tracker Bot` is a Telegram Bot to track your expenses. It is built using [Go](https://golang.org/) and [Postgres](https://www.postgresql.org/). | ||
| `Expense Tracker Bot` is a Telegram Bot to track your daily transactions. | ||
|
|
||
| It's currently supporting a single user. By default, the user is [masudur-rahman](https://t.me/masudur_rahman). | ||
| The `Expense Tracker Bot` is now available for public use. | ||
| To use this bot, go to Telegram and search for [@XpenseTrackerBot](https://t.me/XpenseTrackerBot) | ||
|
|
||
| ## Features | ||
|
|
||
| ## Requirements | ||
| - **Expense Tracking**: Keep track of your daily expenses, income, and balance transfers between accounts. | ||
| - **Flexible Input**: Add transactions interactively by selecting options or simply send a text describing your transaction. | ||
| - **Lending and Borrowing**: Track lendings and borrowings with other individuals. | ||
| - **Transaction Summary**: Retrieve transaction summaries based on type, category, or subcategory for your preferred duration. | ||
| - **Transaction Reports**: Generate transaction reports in PDF format for your chosen duration. | ||
|
|
||
| ### Telegram Bot | ||
|
|
||
| 1. Create a new bot using [BotFather](https://t.me/botfather). | ||
| - Use `/newbot` command to create a new bot. | ||
| - Use `/setname` command to set a name for the bot. | ||
| - Use `/setdescription` command to set a description for the bot. | ||
|
|
||
| 2. Set commands for the bot using `/setcommands` command. | ||
| ``` | ||
| new - Add new Transaction, Account or User | ||
| newtxn - Add new transaction | ||
| user - List persons involved in some loan/borrow with the system user | ||
| balance - List Account Balance | ||
| expense - Fetch Expense of Current month | ||
| summary - Transaction summary of current month | ||
| allsummary - Transaction summary based on Type, Category, Subcategory | ||
| report - Transaction Report | ||
| cat - List Transaction categories | ||
| sync - Sync local SQLite db file to Google Drive | ||
| ``` | ||
| 3. Create a Token for the bot. | ||
| - Use `/token` command to get the bot token. | ||
| #### Telegram Bot Creation Demo | ||
| https://github.com/masudur-rahman/expense-tracker-bot/assets/13915755/bc74ec7a-b243-4faa-a07b-31ebe2260264 | ||
| ## Usage | ||
|
|
||
| ### Database Setup | ||
| Once you are inside the bot inbox, press `Start` button to start using the Tracker Bot. | ||
|
|
||
| #### SQLite (Default) | ||
| Before you start tracking your expenses | ||
| - Add accounts like `cash`, `brac`, `ebl` etc | ||
| - Command `/new` => Account => Type (Cash or Bank) | ||
| - Reply with account details (`cash "Cash in Hand"`, `ebl EBL` etc) | ||
| - Add some debtors/creditors with whom you are financially involved | ||
| - Command `/new` => DebtorsCreditors | ||
| - Reply with the person details (`john "John Doe" [email protected]`) | ||
|
|
||
| By default, the application uses SQLite as its database, requiring no additional setup. | ||
| ### Track your Transactions | ||
|
|
||
| #### PostgreSQL (Optional) | ||
| #### Interactively | ||
| To track your transactions interactively, send `/newtxn` command and follow the on-display suggestions. | ||
|
|
||
| If you prefer to use PostgreSQL, follow these steps: | ||
| #### Regular Text Message | ||
| You also can add new transaction by sending a regular text message. | ||
| You just need to mention | ||
| - what you did | ||
| - how much did it cost | ||
| - when you did it | ||
| - affected accounts | ||
| - affected persons in case of loan/borrow | ||
| - remarks | ||
|
|
||
| ##### Local Setup | ||
| and the bot will take care of the rest | ||
|
|
||
| 1. Install PostgreSQL using [Homebrew](https://brew.sh/): | ||
| ```bash | ||
| brew update | ||
| brew install postgresql | ||
| brew services start postgresql | ||
| ``` | ||
| ##### Obviously you need to follow some rules while adding transactions via text messages. | ||
|
|
||
| 2. Create a superuser named `postgres` with password `postgres`: | ||
| ```bash | ||
| psql postgres -c "CREATE USER postgres WITH SUPERUSER PASSWORD 'postgres';" | ||
| ``` | ||
| Message needs to be in key/value pairs, like: | ||
| - {action} {amount} | ||
| - for {txn subcategory} // the subcategory must match the allowed subcategory | ||
| - {from/to} {account} // default cash | ||
| - {from/to} {debtor/creditor} // in case of lending/borrowing | ||
| - on {date} // "DD-MM-YYY", "YYYY-MM-DD", "MMM DD, YYYY", today, tomorrow, yesterday [default today] | ||
| - at {time} // midnight, morning, noon, afternoon, evening, night and also different time formats [default now] | ||
| - note {remarks} | ||
|
|
||
| 3. Create a new database named `expense`: | ||
| ```bash | ||
| psql -u postgres -c "CREATE DATABASE expense;" | ||
| ``` | ||
| These key/value pairs can appear in any order | ||
|
|
||
| ## Google Drive Access (Optional) | ||
|
|
||
| If you want to back up your SQLite database to Google Drive regularly, follow these steps: | ||
| Some example text for adding a new transaction: | ||
| ``` | ||
| - transferred 2000 from brac to dbbl on 2020-01-01 note "Bill payment" | ||
| - spent 1000 for food-rest on "Jan 13, 2013" from dbbl note "Lunch" | ||
| - earn 5000 to brac on 20-01-2023 note "Salary" | ||
| - borrow 1000 from user to brac on 2020-01-01 | ||
| - return 1000 to user from brac on 2020-01-01 | ||
| - lend 1000 to user from brac on 2020-01-01 | ||
| - recover 1000 from user to brac on 2020-01-01 | ||
| ``` | ||
|
|
||
| 1. [Create a Google Project](https://console.cloud.google.com/projectcreate) (if not already created). | ||
|
|
||
| 2. [Create a Service account](https://console.cloud.google.com/iam-admin/serviceaccounts/create) named `expense-tracker` and download a service account JSON key. | ||
|
|
||
| 3. [Enable the Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com) for your project. | ||
| 4. On Google Drive: | ||
| - Create a folder named `.expense-tracker`. | ||
| - Share this folder with the service account (`expense-tracker@<project-id>.iam.gserviceaccount.com`) and grant it "Editor" permission. | ||
|
|
||
| ## Installation and Running | ||
|
|
||
| ### Local Setup | ||
|
|
||
| 1. Clone the repository: | ||
|
|
||
| ```bash | ||
| mkdir -p $GOPATH/src/github.com/masudur-rahman | ||
| cd $GOPATH/src/github.com/masudur-rahman | ||
| git clone [email protected]:masudur-rahman/expense-tracker-bot.git | ||
| ``` | ||
|
|
||
| 2. Update the configuration file (`configs/.expense-tracker.yaml`) as needed. You can modify the Telegram user and specify the database type. | ||
| ```bash | ||
| telegram: | ||
| user: masudur_rahman | ||
| database: | ||
| type: sqlite | ||
| ``` | ||
|
|
||
| 3. Export required environment variables: | ||
|
|
||
| ```bash | ||
| export TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> | ||
| ``` | ||
|
|
||
| If backing up to Google Drive: | ||
|
|
||
| ```bash | ||
| export GOOGLE_APPLICATION_CREDENTIALS=$HOME/Downloads/service-account-key.json | ||
| ``` | ||
|
|
||
| 4. Run the server: | ||
|
|
||
| ```bash | ||
| make run | ||
| ``` | ||
| ### Docker Setup | ||
| - Write configuration file | ||
| ```shell | ||
| mkdir -p $HOME/.expense-tracker/configs | ||
| echo ' | ||
| telegram: | ||
| user: masudur_rahman | ||
| database: | ||
| type: sqlite | ||
| ' > $HOME/.expense-tracker/configs/.expense-tracker.yaml | ||
| ``` | ||
|
|
||
| - Run Expense Tracker Bot | ||
| ```shell | ||
| docker run -v $HOME/.expense-tracker/configs:/configs \ | ||
| -v $HOME/.expense-tracker:/.expense-tracker \ | ||
| -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> \ | ||
| ghcr.io/masudur-rahman/expense-tracker-bot:v1.0.0 serve | ||
| ``` | ||
|
|
||
| ### Back4App Setup | ||
|
|
||
| 1. Create a new app on [Back4App](https://www.back4app.com/). | ||
| 2. Connect your app to a GitHub repository. | ||
| 3. Set the environment variables to the `Settings.Environment Variables` section. | ||
| 4. Restart the server. | ||
|
|
||
| ### Production Environment (Kubernetes) | ||
|
|
||
| To deploy `Expense Tracker Bot` application in production environment, the preferred way is through Helm Chart. Checkout more [here](https://github.com/masudur-rahman/helm-charts/tree/main/charts/expense-tracker-bot). | ||
|
|
||
|
|
||
| - First you need to add the repo for the helm chart. | ||
| ```bash | ||
| helm repo add masud https://masudur-rahman.github.io/helm-charts/stable | ||
| helm repo update | ||
| helm search repo masud/expense-tracker-bot | ||
| ``` | ||
| - Install the chart | ||
| - For installing just with SQLite database (without Google Drive backup) | ||
| ```bash | ||
| helm upgrade --install expense-tracker-bot masud/expense-tracker-bot -n demo \ | ||
| --create-namespace \ | ||
| --set telegram.token=<TELEGRAM_BOT_TOKEN> \ | ||
| --set telegram.user=<TELEGRAM_USERNAME> | ||
| ``` | ||
| - SQLite with Google Drive backup | ||
| ```bash | ||
| helm upgrade --install expense-tracker-bot masud/expense-tracker-bot -n demo \ | ||
| --create-namespace \ | ||
| --set telegram.token=<TELEGRAM_BOT_TOKEN> \ | ||
| --set telegram.user=<TELEGRAM_USERNAME> \ | ||
| --set database.sqlite.syncToDrive=true \ | ||
| --set-file googleCredJson=<GOOGLE-SVC-ACCOUNT-JSON-FILEPATH> | ||
| ``` | ||
| - Postgres database | ||
| ```bash | ||
| helm upgrade --install expense-tracker-bot masud/expense-tracker-bot -n demo \ | ||
| --create-namespace \ | ||
| --set telegram.token=<TELEGRAM_BOT_TOKEN> \ | ||
| --set telegram.user=<TELEGRAM_USERNAME> \ | ||
| --set database.type=postgres \ | ||
| --set database.deploy=true # set to false if you want to use external database | ||
| # --set database.postgres.user=<POSTGRES_USER> \ | ||
| # --set database.postgres.password=<POSTGRES_PASSWORD> \ | ||
| # --set database.postgres.db=<POSTGRES_DB> \ | ||
| # --set database.postgres.host=<POSTGRES_HOST> \ | ||
| # --set database.postgres.port=<POSTGRES_PORT> \ | ||
| # --set database.postgres.sslmode=<POSTGRES_SSL_MODE> | ||
| ``` | ||
| - Verify Installation | ||
| To check if `Expense Tracker Bot` is installed, run the following command: | ||
| ```bash | ||
| $ kubectl get pods -n demo -l "app.kubernetes.io/instance=expense-tracker-bot" | ||
| NAME READY STATUS RESTARTS AGE | ||
| expense-tracker-bot-7989d96fcc-b4smq 1/1 Running 2 (30s ago) 31s | ||
| expense-tracker-bot-postgres-55dcb67965-95r7g 1/1 Running 0 31s | ||
| ``` | ||
| <details> | ||
| <summary>Expand to see the Allowed Transaction Subcategory list</summary> | ||
|
|
||
| ``` | ||
| Food (food): | ||
| - Restaurants (food-rest) | ||
| - Groceries (food-groc) | ||
| - Takeout (food-take) | ||
| - Snacks (food-snack) | ||
| - Fruits (food-fruit) | ||
| - Beverages (food-bev) | ||
| Housing (house): | ||
| - Rent (house-rent) | ||
| - Utilities (house-util) | ||
| - Furniture (house-furn) | ||
| - Electronics (house-elec) | ||
| - Real State (house-real) | ||
| Entertainment (ent): | ||
| - Movies (ent-movie) | ||
| - Subscription (ent-sub) | ||
| - Recreation (ent-rec) | ||
| - Books (ent-books) | ||
| Personal Care (pc): | ||
| - Salon (pc-salon) | ||
| - Toiletries (pc-toilet) | ||
| - Gym (pc-gym) | ||
| - Clothing (pc-cloth) | ||
| - Health (pc-health) | ||
| - Medicine (pc-med) | ||
| Travel (trv): | ||
| - Accommodation (trv-accom) | ||
| - Dining (trv-dine) | ||
| - Sightseeing (trv-sight) | ||
| - Transportation (trv-trans) | ||
| - Gifts (trv-gift) | ||
| Financial (fin): | ||
| - Salary (fin-sal) | ||
| - Deposit (fin-deposit) | ||
| - Withdraw (fin-with) | ||
| - DPS (fin-dps) | ||
| - Credit Card Payment (fin-ccpay) | ||
| - Bank Transfer (fin-bank) | ||
| - Loan (fin-loan) | ||
| - Loan Recovery (fin-recover) | ||
| - Borrow (fin-borrow) | ||
| - Borrow Return (fin-return) | ||
| - Tax (fin-tax) | ||
| - Charges (fin-charge) | ||
| - Mobile Recharge (fin-flexi) | ||
| Miscellaneous (misc): | ||
| - Initial Amount (misc-init) | ||
| - Giveaway (misc-give) | ||
| - Miscellaneous (misc-misc) | ||
| ``` | ||
|
|
||
| ## Usage | ||
| </details> | ||
|
|
||
| ### Telegram Bot | ||
| You always can send `/cat` command to list the subcategory | ||
|
|
||
| Available commands: | ||
| ### Available commands: | ||
| - `/new` - Add new Transaction, Account or User | ||
| - `user` - Add new user | ||
| - `account` - Add new account (Cash, Bank) | ||
| - `DebtorsCreditors` - Add new debtor or creditors | ||
| - `Account` - Add new account (Cash, Bank) | ||
| - i.e: `brac "BRAC Bank"` | ||
| - `txn` - Add new transaction | ||
| - through some flags | ||
| - i.e: `<amount> -t=<type> -s=<subcat> -f=<src> -d=<dst> -u=<user> -r=<remarks>` | ||
| - i.e: `cash "Cash in Hand"` | ||
|
|
||
| [//]: # ( - `txn` - Add new transaction) | ||
| [//]: # ( - through some flags) | ||
| [//]: # ( - i.e: `<amount> -t=<type> -s=<subcat> -f=<src> -d=<dst> -u=<user> -r=<remarks>`) | ||
|
|
||
| - `/newtxn` - Add new transaction | ||
| - Add a new transaction through a series of callback queries. | ||
| - `/user` - List users | ||
| - `/users` - List users | ||
| - list all the persons involved in some loan/borrow with the system user | ||
| - `/balance` - List Account Balance | ||
| - list all the registered accounts and their balance | ||
|
|
@@ -231,30 +166,11 @@ Available commands: | |
| - `/cat` - List Transaction categories | ||
| - list all the registered categories | ||
| - by selecting a category, list all the registered subcategories of that category | ||
| - `/help` - Show Usage page | ||
|
|
||
| #### More importantly you can add a new transaction just by sending a regular text message | ||
| You just need to mention | ||
| - what you did | ||
| - when you did | ||
| - how much did it cost | ||
| - affected accounts | ||
| - affected persons in case of loan/borrow | ||
| - remarks | ||
|
|
||
| and the bot will take care of the rest | ||
|
|
||
| Some example text for adding a new transaction: | ||
| ``` | ||
| - transferred 2000 from brac to dbbl on 2020-01-01 note "Bill payment" | ||
| - spent 1000 for food-rest on "Jan 13, 2013" from dbbl note "Lunch" | ||
| - earn 5000 to brac on 20-01-2023 note "Salary" | ||
| - borrow 1000 from user to brac on 2020-01-01 | ||
| - return 1000 to user from brac on 2020-01-01 | ||
| - lend 1000 to user from brac on 2020-01-01 | ||
| - recover 1000 from user to brac on 2020-01-01 | ||
| ``` | ||
|
|
||
| ## Live Demonstration | ||
|
|
||
| https://github.com/masudur-rahman/expense-tracker-bot/assets/13915755/83db45c8-1e84-473e-8d58-cda6ef8cc6ef | ||
|
|
||
| ## Future Work | ||
|
|
@@ -263,3 +179,11 @@ A list of possible future work: | |
| - [ ] Add support for undoing a transaction | ||
| - [ ] Add Database backup and restore support | ||
| - [ ] Add support for multiple users | ||
|
|
||
| ## Self Hosting | ||
|
|
||
| If you want to host your own `Expense Tracker Bot`, refer to the [self-hosting](./docs-selfhost) doc page. | ||
|
|
||
| ## Contacts | ||
|
|
||
| Telegram - [masudur-rahman](https://t.me/masudur_rahman). | ||
Oops, something went wrong.