Expense Tracker

A financial tracking and visualization dashboard built with Streamlit for monitoring personal expenses and savings.

What It Does

This application provides a comprehensive view of your personal finances:

• Expense Tracking: Imports and analyzes expense data from bank statement CSV files

  • Categorizes transactions by merchant and category
  • Auto-categorizes grocery store purchases (Sprouts, Safeway, King Soopers, Trader Joe's, Costco, Whole Foods)
  • Groups expenses by date and card
  • Visualizes spending trends over time by category

• Savings Monitoring: Tracks account balances across multiple accounts over time (TBD)

  • Displays savings growth trends
  • Calculates and visualizes monthly savings changes
  • Interpolates daily values from monthly snapshots
  • Compares multiple accounts side-by-side

• Interactive Filtering: Filter data by:

  • Payment cards
  • Expense categories
  • Date ranges
  • Savings accounts

Setup

Requirements

• Python 3.12 or higher
• uv package manager

Installation

1. Clone the repository:

   git clone <repository-url>
   cd expense-tracker

2. Create and setup virtual environment:

   uv sync

3. Activate the environment:

   • On macOS/Linux:

     source .venv/bin/activate

   • On Windows:

     .venv\Scripts\activate

Environment Configuration

Set up the required environment variables for data paths:

export PATH_EXPENSES=/path/to/your/expenses/data
export PATH_SAVINGS=/path/to/your/savings/data

Data Format: The application expects CSV files in these directories. For expenses, the CSV should include columns like:

• Posted Date
• Card No.
• Category
• Debit
• Description
• Paid By
• Paid For

For savings, the CSV should include:

• Account Number
• Transaction Date
• Balance

Usage

Running the Application

streamlit run src/expenses.py  # For expense tracking
streamlit run src/savings.py   # For savings tracking

The application will open in your web browser at http://localhost:8501.

Features

Expense Dashboard:

1. Select which cards to include in analysis
2. Choose expense categories to display
3. Use the date range slider to focus on specific periods
4. View interactive charts showing spending patterns by category and time

Savings Dashboard:

1. Select accounts to monitor
2. Choose your date range
3. View two charts:
   • Savings over Time: Shows account balance trends
   • Monthly Savings: Shows how much balance changed each month

Project Structure

expense-tracker/
├── src/
│   ├── expenses.py      # Expense tracking module
│   └── savings.py       # Savings tracking module
├── data/                # Local data storage
├── pyproject.toml       # Project configuration and dependencies
├── activate.sh          # Environment activation script
└── README.md            # This file

Dependencies

• streamlit: Web app framework
• pandas: Data manipulation and analysis
• plotly: Interactive visualizations
• numpy: Numerical computing
• st-gsheets-connection: Google Sheets integration (optional, for cloud data)

License

See LICENSE file for details.