FinScope

FinScope is a local, single-tenant personal finance web application for importing statement files, categorizing transactions, reviewing unknown merchants, managing rules, and analyzing spending over time.

It is built with Flask, SQLAlchemy Core, SQLite or MySQL, Bootstrap, ECharts, Jinja templates, vanilla JavaScript, JSON translation catalogs, background processing, optional OpenAI AI categorization, and pytest.

DISCLAIMER: This application has been vibe coded using OpenAI's Codex: source code, documentation, tests. The content, code quality, and design has been manually reviewed, but code smells and other problems may still be present. Use with care.

Project owner: Eugene Syriani
Current deployment target: local desktop
License: GNU General Public License v3.0 (GPL-3.0-only)

Quick start | Features | Screenshots | Docs | Testing | License

Key features

• Import CSV statements into SQLite or MySQL storage.
• Deduplicate transactions with account-aware fingerprints.
• Categorize transactions with rules, historical matches, manual edits, optional AI assistance, and persisted decision evidence.
• Review grouped unknown merchants and save reusable categorization rules.
• Check rule health and preview rule changes before applying them.
• Track reimbursements by linking repayment credits to covered expenses.
• Manage categories, tags, merchants, statement types, accounts, processing activity, and recurring activity.
• Analyze spending, income, transfers, tags, merchants, calendars, period changes, and year trends.
• Use owner-managed access for owner, editor, and viewer workflows.
• Switch between English and French, with dark and light interface modes.

Quick start

Minimal local setup on Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item config.example.ini config.ini
finscope

Open http://127.0.0.1:5000, then create the owner account on the bootstrap page. See Getting started for the first-run walkthrough and non-PowerShell command variants.

Development setup

The quick start installs FinScope and its runtime dependencies from pyproject.toml using the tested constraints in constraints.txt. For development, install the Python and frontend toolchains too:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
npm ci

Development uses Python 3.10+ and Node.js 20+ with npm. See Developer guide for platform-specific setup, dependency details, and the full local quality gate.

Documentation

For users

• Getting started: first-run walkthrough from install to the first dashboard review.
• Tutorial: practical workflow and best-practices guide for the first month and beyond.
• User guide: concise feature reference for each major application area.
• Settings reference: all runtime settings available from the Settings page.
• Categories, tags, and categorization: detailed category, tag, rule, historical, and AI categorization reference.
• Troubleshooting: problem/solution notes for local setup, imports, dates, duplicate uploads, and AI categorization.

For developers

• Developer guide: development setup, repository layout, quality checks, and contribution expectations.
• Architecture: module structure, layering expectations, and runtime boundaries.
• Database: SQLite/MySQL backend behavior, schema responsibilities, and generated schema artifacts.
• Testing: pytest markers, suite layout, quality commands, and recommended execution patterns.
• Processing activity: queued workflows, processing state lifecycle, cancellation, and undo behavior.
• Authentication and authorization: owner bootstrap, roles, password handling, settings permissions, and deployment notes.

Testing

The default pytest configuration runs the suite in parallel with strict markers, warnings as errors, collection from tests/, and no coverage slowdown by default.

$env:PYTHONDONTWRITEBYTECODE = "1"
.\.venv\Scripts\python.exe -B -m pytest

See Testing for marker-specific runs, coverage, formatting, linting, type checking, and frontend quality checks.

Before broad changes or release work, run the same local quality gate as GitHub Actions; the command list is in Developer guide.

License

This project is licensed under the GNU General Public License v3.0 only. See LICENSE for the full license text.

Unless a file states otherwise, source files in this repository are distributed under GPL-3.0-only.