FinMind — Personal Finance Manager (GUI)

FinMind is a desktop application for tracking personal income, expenses, and savings goals. It provides analytics, category management, simple advice, and export to Excel and PDF — all in a dark-themed GUI built with CustomTkinter.

The application stores data in a local SQLite database (finmind.db) located in the project directory and creates reports in the Reports/ folder.

Stack detection

• Language: Python 3 (recommended 3.10+)
• GUI: tkinter + CustomTkinter (dark UI)
• Data/Analytics: pandas
• Plotting: matplotlib (TkAgg backend)
• Reports: ReportLab (PDF), pandas to_excel (XLSX)
• Database: SQLite (via Python stdlib sqlite3)
• Package manager: pip (no requirements.txt in repo)

Entry point

• Run the application with: python FinMind.py
  • main() is defined in FinMind.py and guarded with if __name__ == "__main__":.

Overview of features

• Add, edit, delete transactions (income/expense) with categories and comments
• Manage categories (add/delete)
• Savings goals: create, prioritize, mark done/archive, and see estimated time to reach based on recent savings trend
• Analytics: per-month income/expense/savings and savings rate; category totals; month-over-month deltas
• Plots: monthly dynamics, category pie charts, expense histogram
• Exports:
  • Excel: summary and analytics to an .xlsx file
  • PDF: compact A4 report with key metrics and advice (Reports/)
• Simple "advice" panel with data-driven tips
• Dark theme UI

Requirements

• Python 3.10+ (earlier 3.8+ may work; tested environment not specified) [TODO: document exact supported versions]
• OS: Windows, macOS, or Linux with Tk available
• System packages (Linux): ensure Tk is installed (e.g., sudo apt-get install python3-tk or distro equivalent)

Python packages (install via pip):

• customtkinter
• pandas
• matplotlib
• reportlab

[TODO] Add a pinned requirements.txt/poetry/uv file to lock versions.

Setup

1. (Optional) Create and activate a virtual environment

   • Linux/macOS:
     • python3 -m venv .venv
     • source .venv/bin/activate
   • Windows (PowerShell):
     • py -m venv .venv
     • .venv\Scripts\Activate.ps1

2. Install dependencies

   • pip install --upgrade pip
   • pip install customtkinter pandas matplotlib reportlab

3. Verify Tk availability (Linux):

   • python -c "import tkinter; print(tkinter.TkVersion)"

Run

From the project root:

• python FinMind.py

At first run, the app will create:

• SQLite database at ./finmind.db
• Reports directory at ./Reports/

Scripts and automation

No packaging or CLI scripts are provided in the repository.

• Run app: python FinMind.py
• Exports are triggered from within the GUI.

[TODO] Add packaging or convenience scripts (e.g., a Makefile, requirements.txt, or pyproject.toml).

Configuration / Environment variables

The application does not require environment variables for basic operation.

• Database path: hardcoded to finmind.db in the project directory (via FinMind.py constants)
• Reports path: Reports/ in the project directory

[TODO] Make paths configurable via environment variables or CLI flags if needed.

Tests

No automated tests are present in this repository. The application is manually tested via the GUI.

[TODO] Introduce tests for analytics functions (e.g., compute_metrics, allocate_savings_to_goals) and database helpers.

Project structure

Top-level files and directories of interest:

• FinMind.py — main GUI application and all business logic
• finmind.db — SQLite database created/used by the app (can be deleted to reset)
• Reports/ — directory for exported Excel/PDF reports
• LICENSE — MIT License
• README.md — this file
• Other scripts present (not used by the main app): adgs.py, birja.py, birja_skelet.py, first.py, mish.py, skeleton.py [usage unspecified]
• TO DO — notes (if any)

[TODO] Document the auxiliary scripts once their purpose is clarified.

Data model (high level)

• transactions: id (PK), date (YYYY-MM-DD), category, type (income|expense), amount (>0), comment
• goals: id (PK), target_name, target_amount, target_date (YYYY-MM-DD), priority (int; lower is higher), status (active|done|archived)
• categories: id (PK), name (unique)

Tables are auto-created on first run.

Known limitations / notes

• UI language is primarily Russian in labels/text
• Matplotlib backend is set to TkAgg explicitly
• Reports are generated in dark theme PDF using ReportLab
• Paths are relative to the application directory

License

MIT License — see the LICENSE file for details.