💰 Finance Tracker

A comprehensive personal finance management application built with Python, featuring both a command-line interface and an interactive web dashboard for tracking income, expenses, and budgets with ease.

📋 Table of Contents

• Features
• Tech Stack
• Installation
• Usage
  • CLI Commands
  • Web Dashboard
• Project Structure
• Configuration
• Examples
• Future Enhancements
• Contributing
• License

✨ Features

Core Functionality

• ✅ Transaction Management - Add, update, delete, and list income and expense transactions
• ✅ Category Management - Create custom spending categories for better organization
• ✅ Budget Tracking - Set and monitor budgets for specific categories
• ✅ Financial Reports - Generate comprehensive financial reports and insights
• ✅ Real-time Dashboard - Interactive web interface with live financial metrics
• ✅ Data Persistence - All data stored securely in SQLite database

Dashboard Features

• 📊 Current Balance Overview - Real-time income, expenses, and net balance metrics
• 📈 Budget Status Visualization - Visual progress indicators for each budget
• 📋 Recent Transactions Table - Color-coded transaction history with filtering
• 💡 Financial Insights - Quick summary of financial health and spending patterns

CLI Features

• 🖥️ User-Friendly Commands - Intuitive argparse-based command structure
• 📝 Full CRUD Operations - Complete Create, Read, Update, Delete functionality
• 📊 Multiple Report Types - Summary, category-wise, and budget analysis reports
• ⚙️ Date-Based Filtering - Filter transactions and budgets by date ranges

🛠️ Tech Stack

Component	Technology	Version
Language	Python	3.13+
CLI Framework	argparse	Built-in
Web Framework	Streamlit	1.28+
Database	SQLite	3.x
Data Processing	Pandas	2.0+
Package Manager	pip	Latest

📦 Installation

Prerequisites

• Python 3.13 or higher
• pip (Python package manager)
• Git (for cloning the repository)

Step 1: Clone the Repository

git clone https://github.com/yourusername/finance-tracker.git
cd finance-tracker

Step 2: Create Virtual Environment (Recommended)

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Or using the project configuration:

pip install -e .

Step 4: Initialize Database

python main.py init

This creates the SQLite database with all necessary tables.

🚀 Usage

CLI Commands

Database Initialization

python main.py init

Initializes the SQLite database with all required tables.

Category Management

Add a Category:

python main.py add-category "Food"
python main.py add-category "Transportation"

List All Categories:

python main.py list-categories

Update a Category:

python main.py update-category --id 1 --name "Groceries"

Delete a Category:

python main.py delete-category --id 1

Transaction Management

Add a Transaction:

python main.py add-transaction \
  --date 2025-11-18 \
  --amount 50.00 \
  --type expense \
  --category-id 1 \
  --description "Weekly grocery shopping"

List All Transactions:

python main.py list-transactions

Update a Transaction:

python main.py update-transaction \
  --id 1 \
  --date 2025-11-18 \
  --amount 75.00 \
  --type expense \
  --category-id 1 \
  --description "Updated grocery shopping"

Delete a Transaction:

python main.py delete-transaction --id 1

Budget Management

Add a Budget:

python main.py add-budget \
  --category-id 1 \
  --amount 200.00 \
  --start-date 2025-11-01 \
  --end-date 2025-11-30

List All Budgets:

python main.py list-budgets

Update a Budget:

python main.py update-budget \
  --id 1 \
  --category-id 1 \
  --amount 250.00 \
  --start-date 2025-11-01 \
  --end-date 2025-11-30

Delete a Budget:

python main.py delete-budget --id 1

Report Generation

Summary Report:

python main.py report-summary \
  --start-date 2025-11-01 \
  --end-date 2025-11-30

Category Spending Report:

python main.py report-category \
  --start-date 2025-11-01 \
  --end-date 2025-11-30

Budget Status Report:

python main.py report-budget --date 2025-11-18

Web Dashboard

Launch the interactive Streamlit dashboard:

streamlit run streamlit_dashboard.py

The dashboard will open in your default web browser at http://localhost:8501

Dashboard Sections:

1. Current Balance - Overview of total income, expenses, and net balance
2. Budget Status - Visual progress indicators for active budgets
3. Recent Transactions - Last 10 transactions with color-coded types

Deploying to Streamlit Cloud

1. Push your code to GitHub (see deployment section above)
2. Create a Streamlit Cloud account at share.streamlit.io
3. Click "New app" and select:
   • GitHub repository: your-username/finance-tracker
   • Branch: main
   • Main file path: streamlit_dashboard.py
4. Click "Deploy" and wait for the app to build

Note: The database (finance_tracker.db) is automatically initialized on first run. On Streamlit Cloud, the database persists in the app directory for that session.

📁 Project Structure

finance-tracker/
├── main.py                      # Entry point
├── streamlit_dashboard.py       # Web dashboard application
├── pyproject.toml              # Project configuration
├── README.md                   # This file
├── GEMINI.md                   # Gemini integration notes
├── LINKEDIN_POST_PROMPT.md     # Social media prompts
└── finance_tracker/            # Main package
    ├── __init__.py             # Package initialization
    ├── cli.py                  # Command-line interface
    ├── database.py             # Database operations (CRUD)
    ├── models.py               # Data models
    ├── reports.py              # Report generation
    └── __pycache__/            # Python cache directory

File Descriptions

File	Purpose
main.py	Entry point that routes to CLI
cli.py	Argument parser and command handlers
database.py	SQLite database operations and CRUD functions
models.py	Data classes: Transaction, Category, Budget
reports.py	Report generation functions
streamlit_dashboard.py	Interactive web dashboard

⚙️ Configuration

Database

The application uses SQLite with the following schema:

categories table:

CREATE TABLE categories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL UNIQUE
)

transactions table:

CREATE TABLE transactions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    type TEXT NOT NULL,
    category_id INTEGER,
    description TEXT,
    FOREIGN KEY (category_id) REFERENCES categories (id)
)

budgets table:

CREATE TABLE budgets (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category_id INTEGER NOT NULL,
    amount REAL NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT NOT NULL,
    FOREIGN KEY (category_id) REFERENCES categories (id)
)

Dependencies

All dependencies are specified in pyproject.toml:

• questionary>=2.1.1 - Interactive CLI prompts
• rich>=14.2.0 - Rich terminal output formatting
• pandas>=2.0.0 - Data processing
• streamlit>=1.28.0 - Web framework

📊 Examples

Complete Workflow Example

# 1. Initialize database
python main.py init

# 2. Add categories
python main.py add-category "Food"
python main.py add-category "Utilities"
python main.py add-category "Salary"

# 3. Add transactions
python main.py add-transaction --date 2025-11-18 --amount 2500 --type income --category-id 3 --description "Monthly salary"
python main.py add-transaction --date 2025-11-18 --amount 50 --type expense --category-id 1 --description "Dinner"
python main.py add-transaction --date 2025-11-19 --amount 150 --type expense --category-id 2 --description "Electricity bill"

# 4. Set budgets
python main.py add-budget --category-id 1 --amount 300 --start-date 2025-11-01 --end-date 2025-11-30
python main.py add-budget --category-id 2 --amount 200 --start-date 2025-11-01 --end-date 2025-11-30

# 5. View reports
python main.py report-summary --start-date 2025-11-01 --end-date 2025-11-30
python main.py report-category --start-date 2025-11-01 --end-date 2025-11-30
python main.py report-budget --date 2025-11-20

# 6. Launch dashboard
streamlit run streamlit_dashboard.py

🚀 Future Enhancements

Planned features for future releases:

• 📱 Mobile app support
• 📈 Advanced data visualization (charts, graphs, trends)
• 🔐 User authentication and multi-user support
• 💾 Data export (CSV, PDF, Excel)
• 📧 Email reports and notifications
• 🎯 Recurring transactions (auto-bill payments)
• 💳 Credit card integration
• 📊 Machine learning-based spending predictions
• 🌍 Multi-currency support
• ☁️ Cloud sync functionality
• 📱 Push notifications for budget alerts
• 🎨 Customizable dashboard themes

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution Guidelines

• Follow PEP 8 style guidelines
• Add docstrings to new functions
• Update documentation for new features
• Test your changes before submitting PR
• Be respectful and constructive in discussions

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Your Name

• GitHub: @yourusername
• LinkedIn: Your LinkedIn Profile
• Email: your.email@example.com

🙏 Acknowledgments

• Built with Streamlit for the web interface
• Data processing powered by Pandas
• CLI created with Python's argparse
• Inspired by the need for simple yet powerful personal finance management

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed description
3. Include steps to reproduce the problem
4. Share your environment details (OS, Python version, etc.)

📚 Resources

• Python Documentation
• Streamlit Documentation
• SQLite Tutorial
• Pandas Documentation

---

Last Updated: November 18, 2025

Made with ❤️ for personal finance management