personal-finance-tracker-besim 0.1.4

A Streamlit-based personal finance tracker with CSV import, auto-categorization, budgets, and PDF reports.

Personal Finance Tracker

A web application for tracking, analysing, and advising on personal income and expenses, built with Python and Streamlit as a university final project.

---

Project Description

Personal Finance Tracker helps you understand where your money goes — and where it is heading. You can manually add transactions, bulk-import from a CSV bank export, auto-categorize spending, set monthly budgets with visual progress indicators, receive AI-style financial advice and forecasts, and download a formatted PDF report — all stored locally in a SQLite database with no external dependencies.

---

Features

• Dashboard — 4 KPI cards (income, expenses, net balance, transaction count) with vs-last-month deltas; period-filtered pie chart for spending by category; Income vs Expenses grouped bar chart with Savings Rate % overlay; Day of Week spending heatmap highlighting the busiest spending day.
• Budget Manager — Set monthly limits per category; color-coded progress bars (green / amber / red); budget health summary showing how many categories are on track, approaching, or over limit; set to 0 to remove a budget.
• Advisor — Smart financial advisor that analyses the last 3 months of transactions to forecast next-month spending per category (trend-adjusted), surface 4 actionable insight cards (savings outlook, rising categories, top category, saving tip), show a Forecast vs Historical grouped bar chart, and project year-end savings.
• Transactions — Combined page with 3 tabs: view and filter all transactions, add manually with auto-suggested category, or bulk-import via CSV upload with preview.
• Export Report — Select any month/year with data, preview income/expenses/net, and download a formatted PDF report in one click.
• Auto-categorization — Keyword matching assigns categories (Groceries, Transport, Dining, etc.) automatically when importing CSVs.
• Persistent storage — All data saved locally in finance_tracker.db (SQLite, no server required).

---

Installation

# 1. Clone or download the project
cd finance_tracker

# 2. (Recommended) Create a virtual environment
python -m venv .venv
source .venv/bin/activate      # macOS / Linux
.venv\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

---

How to Run

# From inside the finance_tracker/ directory:
streamlit run app.py

The app opens automatically at http://localhost:8501.

To load sample data, go to Transactions → CSV Upload and select sample_data/sample_transactions.csv.

---

How to Run Tests

# From inside the finance_tracker/ directory:
pytest tests/ -v

All tests use an in-memory SQLite database — no files are created or modified. The test suite covers all 5 modules with 83 tests total.

---

Class Overview

Class	Module	Key Attributes	Key Methods	Purpose
Transaction	transaction.py	id, date, description, amount, type, category	to_dict(), from_dict(), from_csv_row()	Data model for a single financial record
DatabaseManager	database.py	db_path	init_db(), insert_transaction(), get_all_transactions(), get_transactions_by_month(), update_category(), delete_transaction(), get_monthly_summary(), set_budget(), delete_budget(), get_budgets()	SQLite persistence layer for all data
Categorizer	categorizer.py	_keywords	categorize(), add_keyword(), get_categories()	Keyword-based auto-categorization engine
ReportGenerator	report.py	—	generate_monthly_report()	Builds and returns PDF reports as bytes
FinancialAdvisor	advisor.py	_db, _df	generate_report(), _compute_forecasts(), _generate_insights()	Forecast and insight engine
CategoryForecast	advisor.py	category, predicted_amount, avg_last_3_months, trend_pct, months_of_data	—	Dataclass: per-category spending prediction
SpendingInsight	advisor.py	level, message, category	—	Dataclass: one actionable insight
AdvisorReport	advisor.py	forecasts, insights, predicted_total_expenses, predicted_savings, current_month_income, savings_by_year_end, top_spending_category, busiest_day_of_week	—	Dataclass: full advisor output

Helper functions in utils.py: parse_csv(), format_currency(), get_month_range()

---

CSV Format

The CSV import requires a header row with the following columns:

Column	Type	Format	Example
date	string	YYYY-MM-DD	2026-05-10
description	string	Free text	REWE Supermarket
amount	number	Positive decimal	52.30
type	string	income or expense	expense
category	string	(optional)	Groceries

If category is omitted, it is assigned automatically from the description.

See sample_data/sample_transactions.csv for a ready-to-use example with 48 transactions.

---

Project Structure

finance_tracker/
├── app.py                        # Streamlit entry point (5 pages)
├── advisor.py                    # Smart financial advisor engine
├── database.py                   # SQLite persistence layer
├── transaction.py                # Transaction dataclass
├── categorizer.py                # Keyword-based categorizer
├── report.py                     # PDF report generator (fpdf2)
├── utils.py                      # CSV parser and helper functions
├── finance_tracker.db            # Created automatically on first run
├── tests/
│   ├── conftest.py               # sys.path setup for pytest
│   ├── test_transaction.py       # 16 unit tests for Transaction
│   ├── test_categorizer.py       # 14 unit tests for Categorizer
│   ├── test_database.py          # 24 unit tests for DatabaseManager
│   ├── test_advisor.py           # 18 unit tests for FinancialAdvisor
│   └── test_utils.py             # 11 unit tests for utils helpers
├── sample_data/
│   └── sample_transactions.csv   # 48 realistic sample transactions
├── pyproject.toml                # Packaging metadata (bonus)
├── requirements.txt
└── README.md

---

Technologies Used

Library	Purpose
Python 3.10+	Core language
Streamlit	Web UI framework
Pandas	DataFrame manipulation and CSV handling
Plotly	Interactive charts
fpdf2	PDF report generation
SQLite3	Built-in database (no server needed)
pytest	Unit testing (83 tests across 5 modules)