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 paycheck arrives (~25th of month, flexible)
• Ends when next paycheck arrives
• All calculations are relative to 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

Variable spend (groceries, fuel) is not modelled here — it comes from Category Budgets, which derive expected spend from real bank transactions. Two independent settings per category:

• Budget (CategoryBudget) picks the monthly figure: Average / Median over the last N completed months (blank = all history), or Fixed — a typed amount, history ignored. Leading/trailing empty months are never counted, so a short history isn't diluted by a long window; interior gap months count as zero.
• Type (CategoryBudgetType) spreads that figure over the period: Steady / Bill / Subscription, with a per-period manual override of what's remaining.