HomeBalanceMonitor
A family web application to keep income and expenses of bank accounts and credit cards in one place, read-only. The foundations and the manual register with file import are built.
The idea
I’d like one place where the family can see what comes in and what goes out, instead of looking at each bank separately. HomeBalanceMonitor is meant to be that place: a multi-user web application, used only inside the home network, where movements arrive in three ways: read-only synchronisation through an Open Banking service, import from the banks’ CSV/Excel files and manual entry. It never makes payments: it only uses read access.
The design comes first
So far there is no application code, only a requirements document and a test script. I wanted the constraints on paper before writing anything, because several of them change the shape of the project:
- Account holder, app user and the person who authorises are different things, so permissions are set per user and per account (none, read, write), and how an account is fed (API or file) is a setting of that account.
- Consent is not forever. An Open Banking authorisation lasts a limited time, with no refresh: it has to be renewed with the bank’s strong authentication. The plan includes a status page and email warnings before expiry.
- Banks limit reads when nobody is present, so the application syncs a couple of times a day, plus a “Sync now” button.
- History can shrink shortly after the authorisation, so the full download starts right after the consent, and imported files fill any gap.
- Avoiding double counting is most of the work: the bank’s original data is kept untouched, categories and notes live apart, transfers between our own accounts don’t count as income or expense, and card statements are matched to their charge on the account. De-duplication uses the bank’s reference when it exists, and anything ambiguous goes to a manual review, never to an automatic merge.
On the technical side: Python with FastAPI and PostgreSQL, server-side pages with HTMX instead of a single-page app, Docker, HTTPS, restricted access, amounts as exact decimals and never floating point, logs that never contain financial data, secrets kept out of the repository, and encrypted backups with a documented restore test.
What’s built so far
Two phases are done and installed. The first laid the foundations: login, per-user and per-account permissions, an administration page, HTTPS, encrypted backups and an update script. The second is the register: movements, import from files, categories, balances and search.
The one non-obvious choice is the import. Instead of a fixed format for each bank, I show a preview, I choose which column is the date, the amount and the description, and the choice is saved on the account for the next time. My first guess at the header was wrong on the first real file, because the bank had put a few lines of notes above it; now the header is recognised even with notes on top. I also check my own data on the Mac by printing only structure and counts, with the figures masked.
Status
Work in progress. Requirements and architecture are written, the foundations and the register are in use, and a first test against a bank worked. Not tried yet: real email delivery, a restart after the weekly reboot, and the internal pages on a real phone. Next comes the automatic sync (only when I decide to start it), then matching and reconciliation, and last a security review and a guide for the family.
Stack
Python · FastAPI · PostgreSQL · SQLAlchemy · HTMX · Docker