A local-first personal finance dashboard. Exact-cent accounting, user-managed categories, budgets, insights, and a dependency-free canvas UI. Your data never leaves your machine.
Features · Quick start · Architecture · API · Data model · Privacy
Finlify is a single-user finance tracker you run yourself. It keeps a plain SQLite file on your disk, serves a fast dark dashboard, and does all of its money maths in integer cents so totals never drift. There is no account, no cloud sync, no analytics, no CDN, and no telemetry. Start it, open the browser, and your ledger is there.
The whole thing is deliberately small: a few hundred lines of Python, vanilla
JavaScript, and hand drawn <canvas> charts. It works offline and installs in seconds.
| Area | What you get |
|---|---|
| Exact money | Every amount is stored and summed as integer cents. Floats are used only to render text, never to add up balances. |
| Dashboard | Balance, income, expenses, savings rate, this-month figures, average daily spend, and a projected month-end total. |
| Insights | Largest expense, top spending category, and the biggest month-over-month jump. |
| Charts | Income vs. expense area chart, category donut, budget bars, and a daily spend sparkline — all drawn locally on <canvas>. |
| Categories | Full create, rename, recolor, archive, and delete. Renaming rewrites history so nothing is orphaned. |
| Budgets | Monthly limits per category with ok / warn / over states at 80% and 100%. |
| Ledger | Filter by type, category, and text; sort, paginate, edit, and delete entries. |
| Backup | One-click JSON export and an idempotent import that never duplicates money. |
| Zero drift | Idempotent migrations run on every boot; re-running them is a no-op. |
Requires Python 3.11 or newer.
git clone https://github.com/matkecn/finlify.git
cd finlify
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reloadOpen http://127.0.0.1:8000.
On first run Finlify creates finlify.db beside the code and seeds a starter set of
income and expense categories. Delete the file to start over.
pip install --user -r requirements.txt
uvicorn main:app --host 127.0.0.1 --port 8000Migrations run automatically at startup, but you can also run them directly:
python migrations.py| Variable | Purpose | Default |
|---|---|---|
FINLIFY_DATA_DIR |
Directory that holds finlify.db. Useful for tests and throwaway instances. |
Project root |
FINLIFY_DATA_DIR=/tmp/finlify-demo uvicorn main:app --port 8001Finlify is three layers and a single file.
flowchart LR
UI["Browser UI<br/>vanilla JS + canvas charts"]
API["FastAPI<br/>main.py"]
MONEY["money.py<br/>exact integer cents"]
MIG["migrations.py<br/>idempotent, on boot"]
DB[("SQLite<br/>finlify.db")]
UI -- "HTTP / JSON" --> API
API --> MONEY
API -- "SQLAlchemy ORM" --> DB
MIG -- "schema + seed" --> DB
main.py— page, API routes, validation, analytics, export/import.models.py— theTransaction,Category,Budget, andAppMetaORM models.money.py— decimal to cents conversion with half-up rounding and a hard cap.migrations.py— upgrades the legacy float schema to integer cents and seeds categories.database.py— engine and session factory; honoursFINLIFY_DATA_DIR.static/+templates/— the dashboard, charts, and styles.
Binary floating point cannot represent 0.10 or 19.99 exactly, and summing such
values drifts over time. Finlify avoids the problem entirely:
- User input arrives as a decimal (
"19.99"). - It is converted once to integer cents with half-up rounding (
1999). - All storage, aggregation, and comparison happens on integers.
- A float is produced only at the edge, for display, alongside the exact
*_centsvalue so a client can verify totals without reintroducing drift.
Unclassified legacy rows (a type that is neither income nor expense) are
counted in the ledger but excluded from every monetary total, so old or malformed
data can never distort a balance.
transactions
| Column | Type | Notes |
|---|---|---|
id |
integer | Primary key |
amount_cents |
integer | Exact minor units, never a float |
type |
text | income or expense |
category |
text | Category name; text, not a foreign key, so history survives renames |
description |
text | Optional, up to 140 characters |
date |
date | ISO YYYY-MM-DD |
categories
| Column | Type | Notes |
|---|---|---|
id |
integer | Primary key |
name |
text | Unique, normalised, up to 40 characters |
kind |
text | income or expense |
color |
text | Hex colour used by the charts |
is_archived |
boolean | Hidden from pickers without deleting history |
sort_order |
integer | User-defined ordering |
budgets
| Column | Type | Notes |
|---|---|---|
id |
integer | Primary key |
category |
text | Unique expense category name |
limit_cents |
integer | Monthly limit in exact cents; 0 clears tracking |
app_meta — a small key/value table holding schema_version and bookkeeping.
Interactive docs are generated by FastAPI at http://127.0.0.1:8000/docs.
| Method | Path | Purpose |
|---|---|---|
GET |
/ |
The dashboard page |
GET |
/api/health |
Status plus database path and row counts |
GET |
/api/summary |
Full dashboard summary, totals, and insights |
GET |
/api/timeseries?months=6 |
Monthly income, expense, and net totals |
GET |
/api/breakdown?months=6&type=expense |
Per-category totals and shares |
GET |
/api/daily?days=30 |
Per-day totals for the sparkline |
GET |
/api/transactions |
Filtered, sorted, paginated ledger page |
POST |
/api/transactions |
Create a transaction |
PUT |
/api/transactions/{id} |
Replace a transaction |
DELETE |
/api/transactions/{id} |
Delete a transaction |
GET |
/api/categories?include_archived=false |
List categories |
POST |
/api/categories |
Create a category |
PUT |
/api/categories/{id} |
Partial update, including rename with history rewrite |
DELETE |
/api/categories/{id} |
Delete a category (refused if it is in use) |
GET |
/api/budgets |
Budgets with current-month spend |
PUT |
/api/budgets/{category} |
Create or update a monthly limit |
DELETE |
/api/budgets/{category} |
Remove a budget |
GET |
/api/export |
Download a versioned JSON backup |
POST |
/api/import |
Restore or merge a backup (idempotent) |
GET |
/dashboard |
Legacy totals payload for older bookmarks |
curl -X POST http://127.0.0.1:8000/api/transactions \
-H 'Content-Type: application/json' \
-d '{"amount": "19.99", "type": "expense", "category": "Groceries", "date": "2026-09-30"}'{
"id": 1,
"amount": 19.99,
"amount_cents": 1999,
"type": "expense",
"category": "Groceries",
"description": null,
"date": "2026-09-30",
"classified": true
}finlify/
├── main.py # FastAPI app: routes, validation, analytics
├── models.py # SQLAlchemy models (integer-cent columns)
├── money.py # Decimal <-> cents with half-up rounding
├── migrations.py # Idempotent migrations + default categories
├── database.py # Engine, sessions, FINLIFY_DATA_DIR support
├── requirements.txt
├── requirements-dev.txt # Test dependencies
├── pytest.ini
├── templates/
│ └── index.html # Single-page dashboard
├── static/
│ ├── app.js # Dashboard controller
│ ├── charts.js # Canvas chart engine
│ ├── style.css # Theme
│ └── favicon.svg
├── assets/ # Logo, icon, and banner used in this README
└── tests/ # Pytest suite
├── test_money.py
├── test_models.py
├── test_migrations.py
└── test_api_*.py
- No network calls at runtime. The page loads only local assets; the charts are drawn in the browser.
- No accounts, no analytics, no telemetry, no third-party services.
- Your ledger lives in a single SQLite file on your disk, and the database is
excluded from version control by
.gitignore.
Run it on 127.0.0.1 and it is reachable only from your machine.
- Export: click Export in the dashboard, or
GET /api/export, to downloadfinlify-backup-YYYY-MM-DD.jsonwith every transaction, category, and budget. - Import: click Import, or
POST /api/import. Merging is the default and is idempotent — a transaction that already exists (same date, type, category, amount, and description) is skipped, so importing the same file twice never double-counts. Send{"replace": true, ...}to restore instead of merge.
The suite uses pytest and runs against a throwaway database, so it never touches your ledger.
pip install -r requirements-dev.txt
pytestIt covers the exact-cent money layer, model validation, the idempotent migrations, and every API endpoint — including the integer-cent totals, category rename cascades, budget thresholds, and the idempotent export/import round trip.
Released under the MIT License.