Personal finance aggregator: Savings projections - Part 16

Personal finance aggregator: Savings projections - Part 16

Building Finance System

~8 min read

Everything so far has looked backwards: what I spent, what I owe, what the balance was. The savings and projection commit and its follow-up (build on savings add anni date) look forward. The Savings page takes any savings account - synced or manual - and projects its balance twelve months out, given an interest rate and a monthly contribution. It's a small amount of maths, and nearly all of the interest is in making the assumptions explicit, so this post is mostly about those.

The model, in a docstring

savings.py opens with the model, and it's worth reading before the code because it's honest about what it doesn't do. The projection is "gross (no tax) and deliberately simple". The rate is the account's gross nominal annual rate - "the figure banks quote alongside 'paid monthly' or 'paid yearly' - not the effective AER." The two payment frequencies behave differently:

  • Monthly: interest is credited each month at rate/12 on the balance, so it compounds monthly. 5% paid monthly grows to about 5.12% over a year.
  • Yearly: interest accrues at rate/12 each month on the credited balance but isn't added until the anniversary, so it doesn't compound within the year. 5% paid yearly grows to exactly 5%.

There's one more rule that matters, and it's the kind of thing that's easy to get subtly wrong: the monthly contribution lands "at the end of each month, after that month's interest, so it starts earning from the following month." Fixing the order of those two events in writing means the tests have a definite thing to check.

Like categorization.py and budgets.py before it, this is a module of pure functions - no database, no HTTP. project() takes a balance, rate, frequency, contribution and start date and returns the totals plus one point per month-end. That made it easy to test exhaustively, and it's why the API route that wraps it stays short.

One point per month-end

Each projected point is "what the account would show then: credited money plus any interest accrued but not yet paid out". For a yearly account that's a meaningful choice: between anniversaries, accrued interest is real money the bank owes you but it isn't in the balance yet. Showing credited-only would make the line sit flat and then jump; including accrued shows steady growth, and the totals (interest_earned, contributions, end_balance) are kept separately so the page can show each.

Settings live beside the account, not in it

Savings configuration is per-account metadata - a rate, a frequency, a contribution - and it follows the rule from post 11: user-authored data doesn't go in tables a sync rewrites. It gets its own savings_settings table, keyed (bank, account_id) exactly like the alias table so that one table works for synced and manual accounts alike. Its comment states the lifecycle: "a row only exists once the user has set it up - no row means the account has no projection yet." An account without settings simply shows its balance; the projection appears when there's something to project.

The API's GET /api/savings returns every account with kind='accounts' (the non-debt ones), attaching a projection to those with settings, and PUT /api/savings/{bank}/{account_id} saves the settings. Cards are rejected with a 400, since a debt doesn't earn interest.

The anniversary: a bug in the first version

The first version of yearly interest paid out "12 months from now". That isn't how savings accounts work: interest is paid on the account's anniversary, whenever that happens to fall. A projection that credits it in the wrong month is wrong in every month of the chart.

The follow-up fixes it by asking for the anniversary date. The interesting detail is how little of it is used - only the month matters, since projection points are month-ends:

def _credits_interest(month_of_year, months_from_start, anniversary):
    if anniversary is None:
        return months_from_start % 12 == 0
    return month_of_year == anniversary.month

A test pins the behaviour with arithmetic you can check by hand: an account opened in March paying 12% yearly credits at the end of March 2027, the sixth point, with 1000 becoming 1060 credited, then six more months of simple interest accruing on top (£10.60 a month) for an end balance of 1123.60.

Three smaller details show how the change was threaded through:

  • Validation at the edge. The API now returns a 422 if frequency is yearly and there's no anniversary date - "Yearly interest needs the anniversary date it's paid on". The model has a sensible fallback (12 months from start), but a user choosing yearly is told to supply it.
  • Clearing stale data. If an account is switched back to monthly, the stored anniversary is set to None - only yearly accounts have one, and keeping an ignored date around invites it being misread later.
  • A migration that preserves behaviour. The column is added with the usual PRAGMA table_info guard, and rows saved before it existed read back NULL, "which keeps their old 12-months-from-today projection until the user sets a date." Old rows keep working exactly as before, without a backfill.

The frontend keeps its form fields as strings, so half-typed input like 4. doesn't get rewritten under the cursor, and only parses on save. It also formats the anniversary in UTC - a bare YYYY-MM-DD shifts by a day in timezones west of UTC if formatted in local time.

A chart that joins the past to the future

The page started as a list of cards, each with its own projection. A later commit added one chart for all of them, and the interesting decision is how it joins history to projection. Each account gets two series: a solid line of recorded balances from the account_balance_history table (post 13), limited to the last six months, and a dashed line for the projection. The dashed series starts at today's balance - the same point the solid one ends on - so the two lines meet instead of leaving a gap. An account with no settings simply has no dashed line. Reference lines mark today and six months ahead, and the x axis is a real time scale rather than a category per point, so months with no snapshot don't get an evenly spaced slot of their own.

History is treated as a nice-to-have: if the request for it fails, the chart falls back to the balance now plus the projection, rather than the page showing an error.

Choosing which accounts appear

Every account with kind='accounts' used to show up here, including a current account you'd never project. The Accounts page now has a "Show on Savings" checkbox per account, and the storage for it is a small table of accounts that are hidden, not a flag defaulting to shown:

SAVINGS_HIDDEN_SCHEMA = """
CREATE TABLE IF NOT EXISTS savings_hidden (
    bank TEXT NOT NULL,
    account_id TEXT NOT NULL,
    PRIMARY KEY (bank, account_id)
);
"""

The comment above it gives the reason: with a hidden-list, every savings account is visible until you opt it out, no row is needed for the default, and there is no migration for existing users. PUT /api/savings/{bank}/{account_id}/visibility inserts or deletes the row, hiding keeps the account's projection settings, and deleting a manual account clears its hidden row along with its settings. It's the same shape as the alias and settings tables: per-account state lives in a table keyed (bank, account_id), beside the account rather than in it.

Tab titles, and other small UX

The UX improvements commit is the least technical in the series but worth a mention. It replaces the Vite default <title>frontend</title> with "Finance System", swaps the stock favicon for a small chart-line icon, and adds a PageTitle component that keeps document.title in step with the route: "Budgets · Finance System", or for a drill-down, "Groceries · Budgets · Finance System" - the most specific part first, so tabs stay readable when several are open at once. Its lookup table is keyed by the first path segment, so a new route "only needs a line here". It's a few dozen lines, and it's the commit that makes the app feel like a product rather than a localhost project.


Previous: ← Budgets · Next: Making the nightly sync boring →