ssbudget: Instructions file for Claude Code

SSBudget - Claude Context File

Project Overview

Personal budget tracker for tracking monthly expenses, bank balances, and calculating available spending money. Internet-facing with passkey authentication (no user management).

UI Design Principles

Spreadsheet-like efficiency - The UI should feel like a well-designed spreadsheet:

• Concise: Maximum information density, minimal chrome
• Direct manipulation: Edit in place, no unnecessary modals or multi-step wizards. But explicit submission is ok when needed
• Minimal clicks: Common actions (update balance, mark paid) should be 1-2 clicks
• Scannable: Numbers aligned, status visible at a glance

Think "Google Sheets for personal budget" not "enterprise dashboard with cards everywhere".

Core Concepts

Period

• Starts when a paycheck arrives; closed by hand when the next one does
• Carries its own expectedEnd date. Nothing infers it from a payday — the app's only opinion is the date it PROPOSES when a period opens (Period.defaultExpectedEnd: the same day of the following month), and that is editable in place on the Periods page. Days left, day N and the progress bar all read that one date, so a paycheck landing early or late is a one-field fix rather than a rule change
• An open period past its expectedEnd overruns (days remaining go negative) instead of rolling forward, so being late to close it stays visible
• A second paycheck inside a period is not a period boundary: it is a planned income, and so reaches free money through Pending Income. Timing is deliberately not modelled — the app takes an approximate, eventually-consistent view of when money lands, because dating every expense would cost more effort than the precision is worth
• All calculations are relative to the current period

Budget Items

Planned Items - anything you expect to move this period, expense or income (rent, subscriptions, salary, a savings top-up)

• Have an estimated amount
• Are paid in one go or in instalments: each payment ADDS to the period's paid total
• settled is what closes an item — "nothing more expected this period", however little was actually paid. A bill that comes in cheaper than its estimate settles at the lower amount instead of leaving a residual
• Remaining (estimate - paid, or 0 once settled) is what feeds predicted expenses
• There is deliberately no automatic scaling: an item is either expected in full, part-paid, or settled