Rich Secret 💰

Rich Secret is a personal budgeting web application built using Streamlit. It helps you track, plan, and analyze your finances with ease, leveraging a Google Sheets template.

---

Features

Setup

1. Google Sheets Integration:

   • Make a copy of the provided Google Sheets Template and populate it with your data.
   • Ensure the sheet is shareable (Anyone with the link can view).
   • Input the link to your sheet into the app.

2. Template Sheets Overview:

   • monthly_plan: Plan your monthly expenses, income, and savings.
   • expenses, income, savings: Track actual financial data.
   • categories: Data validation and customization.
   • init: Initial balance and savings data.

   (Detailed instructions can be found in the README within the Google Sheets template.)

App Functionalities

1. Settings Section:

   • Select a time mode (Month, Quarter, Year, or Custom to specify date range).
   • Choose a display currency.
   • Aggregate data by 1, 3, 7, 14, or 30 days in visualizations.
   • Option to hide Fixed expenses in visualizations.

2. Stats Section:

   • Balance, total income, total expenses, total savings.
   • Weekly spend/allowance.
   • Changes from the previous period in both absolute and percentage terms.

3. Plots (Powered by Plotly):

   • Dumbbell plots comparing planned vs actual amounts for expenses, income, and savings.
   • Aggregated time-series plots:
     • Ridgeline-like Plot: Expenses distribution by category.
     • Balance Overview: Lineplot of balance with lollipops showing changes to balance by income, expenses, and savings.
     • Savings Overview: Stacked area plot of savings by category.

All plots are interactive and feature detailed hover tooltips.

---

How to Run Locally

1. Clone the repository:

   git clone https://github.com/yourusername/rich-secret.git
   cd rich-secret

2. Install dependencies (Python 3.12):

pip install -r requirements.txt

3. Configure the currency conversion API:

• Register at fxratesapi.com to obtain an API key.
• Save the key in .streamlit/secrets.toml located in the same folder as app.py:

  fxrates_api = "fxr_live_{your_api_key}"

4. Run the app:

streamlit run app.py

5. Access the app at http://localhost:8501.

P.S. For local use you can set up a Google Sheets link in .env:

SHEETS_LINK = https://docs.google.com/spreadsheets/d/your_sheets_id/edit?usp=sharing

App screenshot

It features custom plotly figures such as dumbbell plots, ridgeline plot with data dots, shifted lineplot with lollipops, stacked area:

Optional Automation: SMS to Google Sheets (Personal Setup)

In addition to the Streamlit dashboard, Rich Secret includes a personal automation pipeline:

• SMS Forwarder App on phone: detects incoming bank messages and forwards them to a private Telegram channel (using tg_bots/forwarder_bot).
• Telegram Bot inside the channel (tg_bots/parser_bot): parses transaction details from each SMS and writes them into the linked Google Sheets template used by the app.

This automation is currently tailored to a specific bank’s SMS format and is used privately. If you’re interested in a similar setup, feel free to reach out or adapt it for your own use case.