💸 FinFlow — Personal Finance Dashboard

A personal budgeting application, built with PyQt6, SQLAlchemy 2.0, and PostgreSQL — running seamlessly via Docker Compose.

Features

• Track income, expenses, and goals with an intuitive GUI.
• Auto-starting PostgreSQL container (no manual DB setup).
• Charts for expenses and budget allocation (Matplotlib).
• Import/Export (CSV, JSON).
• Modular SOLID architecture with SQLAlchemy ORM.
• Cross-platform (macOS, Windows, Linux).

Quick Start

Prerequisites

• Docker + Docker Compose v2
• Python 3.11+
• Poetry

Setup

git clone https://github.com/yourname/finflow.git
cd finflow
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head

Recommended way to setup/develop the app is listed under system-setup document.

Run the app:

python run_with_docker.py

Stopping

When you close the app, Docker containers shut down automatically. Data persists in the dbdata Docker volume.

Testing

• Run all tests:

  pytest -v

• Lint with ruff or flake8

• Type-check with mypy

Tech Stack

• Frontend: PyQt6 + Matplotlib | Future:
• Backend: SQLAlchemy 2.0 ORM
• Database: PostgreSQL 16
• DevOps: Docker Compose
• Testing: pytest

Future Enhancements

• Cloud sync via Supabase
• Multi-user accounts
• Web interface
  • ReactJS or NextJS
• Mobile-responsive UI (Qt for Android)
  • or ReactNative
• AI-based expense categorization

Code Style

• Follow PEP8 and SOLID principles

• Use SQLAlchemy ORM models

• Commit messages use Conventional Commits, e.g.:

  • feat(ui): add export to JSON
  • fix(db): resolve duplicate key issue

• Git Branching strategy:

  • Always include the issue number first, then a short, case summary, e.g.:
  • docs/12-add-documentation-files

• For details on git commit message, brnaching strategy and other relevant part, refer to git-branching-guide document.