Replacing My Cash-Flow Spreadsheet with a Local App
I tracked my money in a spreadsheet that started over every period. Each new file opened with the last one's closing balance, transfers took two rows, and the summary tabs were formulas I had to trust. Checking my balance from my phone meant opening a sheet that was never built for a small screen.
In November I replaced it with a small app that runs on my laptop. This note covers how it stores money, how the old sheets came in with every balance checked, how I reach it from my phone, and the parts I got wrong on the way.
The workbook had a tab for transactions, one for accounts, one each for types and categories, a summary, and a wealth tab for savings, stock, gold, and money I had lent. Only two of those held real data: the transactions and the wealth values. Everything else was a rollup.
The trouble was the rollover. Each file covered a period and began with an “Initial Balance” row per account, copied from the previous file. If I mistyped one, the new file was quietly wrong, and nothing compared it with the old one. A transfer between accounts was two rows that had to cancel out. There was no budget and no way to plan for something I was saving toward.
Why No Framework
The app is a Python 3 server that uses only the standard library, a browser interface in plain JavaScript, and JSON files on disk. There is nothing to install and no build step. I had already built an invoice tool the same way. For one person’s data on one laptop, I wanted something that runs with Python 3 and a browser and nothing else.
The JSON files are written atomically, so a crash halfway through a save leaves the old file in place. Backups are a copy of the folder.
How It’s Built
01
BrowserOne JavaScript module per screen, inline SVG charts
02
Local serverJSON API on 127.0.0.1, checks Host and a write header
03
CoreValidation, balances, and reports, with no HTTP code
04
JSON filesAccounts, categories, transactions, wealth, goals, budgets, and members
A few rules in the data model removed most of the spreadsheet’s problems:
Amounts are integer hundredths of a rupiah. A balance with decimals stays exact, and no float rounding creeps into the totals.
A transfer is one entry with a from account and a to account. It is never counted as income or expense.
An opening balance is its own transaction type, so accounts have no hidden starting number.
A wealth holding has a dated history of values, and its current value is the newest point.
The rollups are computed. Only transactions, holdings, and settings are stored.
Within a day, entries keep the order I give them. I can drag a row, use the arrow keys on its handle, or move it from the edit dialog. The order never changes a balance or a report.
Importing the Old Sheets
The importer reads .xlsx files with the standard library, since an xlsx is a zip of XML files. By default it is a dry run: it converts the workbook, merges each pair of transfer rows into one transfer, and compares the account balances and the wealth total with the sheet’s own numbers. --apply runs the same checks and writes nothing if one fails. It also refuses to run when data already exists, so I cannot import twice by accident.
The rollover needed its own logic. When several files come in, each file’s opening balance is compared with the running balance from the file before. If they agree, the opening row is skipped as a carry-over. If they differ, the importer adds a visible “Balance adjustment” entry on the day after the earlier period ends, so every account still ends on the newest sheet’s balance. Dropping the difference would have hidden it.
That happened once. Two accounts in my second sheet had opened lower than the first sheet closed, and the import made the gap two entries I can see and delete. Rows the converter had to interpret are printed as notes: an “Other” row is income when positive and an expense when negative, and a transfer with no other side, such as money moved to a foreign-currency pocket, stays a plain entry.
I imported two archived sheets first and then the current one with --append, which backs up the data folder before it writes and refuses a file that is not newer than what is there. The result was 349 transactions from late August to November 10 and 8 holdings, and every balance matched the sheets.
What It Does
The dashboard shows the net total, wealth, the change since yesterday, this month against last month, top expenses, and account balances.
Transactions can be filtered by search, account, category, type, and dates.
Goals break something I am saving for into items, each with a planned cost and what I have put aside so far.
Budget sets one monthly limit per expense category and shows each month’s spending against it, tightest first.
Wealth groups holdings and keeps each one’s value history.
Reports show a year at a glance, income and expense by month, net worth over time, and a category table, with export to CSV or a JSON backup.
Design
The interface follows coss ui, ported by hand to plain CSS because there is no React or Tailwind build. It uses Geist and Geist Mono only, a neutral gray palette with one blue accent, and color only where it means something: green for income, red for expenses, and a green-to-red meter for budgets. Deleting a transaction shows a message with Undo, which puts it back with the same id in the same place, so there is no confirmation dialog.
It took four looks to get there. The first matched this site, an editorial finance style came next, and on November 16 I switched to coss ui. Three days later I cut it down to a compact monochrome dashboard and dropped the extra fonts and the per-category colors.
Reaching It from a Phone
The app stays on my laptop. A Cloudflare Tunnel connects a hostname to the local port, and Cloudflare Access decides who can sign in, with an email one-time PIN. make online starts the server in online mode and opens the tunnel, and make offline closes both.
The server does not rely on Access alone. Every request must carry Access’s signed token, and the server checks the RS256 signature against the team’s public keys, plus the audience, issuer, and expiry. Python’s standard library has no RSA, so the verification is a short hand-written PKCS#1 check with tests of its own.
The owner can edit everything. Anyone else Access lets in can view everything and edit only the areas the owner ticks for them under Settings: transactions, goals, budget, wealth, or accounts and categories. The server refuses their other writes, and the interface hides the controls they cannot use.
Safety
Offline, the server listens only on 127.0.0.1, rejects requests whose Host header is not local, and accepts writes only with a custom X-Ledger header. A web page on another site cannot send that header without a CORS preflight the server never approves, so it cannot change my data. The repository holds no real data: data/ is ignored by git, and the 75 unit and API tests use made-up names and figures.
Limitations
There is no restore button. Restoring means stopping the app and copying the files back. Phone access only works while the laptop is on and online. The --host 0.0.0.0 option, which opens the app to the local network, has no login at all, so I only use it on a network I trust. Money lent between people is still recorded as plain income and expense, so the totals match the sheet. A loan feature is not built.
Lessons
Check imported totals against the source
The importer’s balance check is what found the gap between two sheets. Without it, the adjustment would have disappeared into the starting balance.
Store a choice instead of guessing it from a name
An early version picked an account’s group and a goal item’s icon by reading its name. I replaced that with a stored type and an icon picker, and anything saved without an icon falls back to a fixed default.
Check the screen by eye
A chart class once shared its name with a header rule, and the bars broke. Every check that counted elements passed; only a screenshot showed it. I prefix component classes now and check both themes by eye.
Settle the design early
Each restyle touched every screen, and there were four in nine days.