The Brief: Personal Finance CLI

The Brief: Personal Finance CLI

Build a command-line expense tracker. No tutorial, no starter solution — this page is your requirements document, the way a real project begins.

Product requirements

• Record expenses: amount (> 0), category (free text, stored lowercase), and an optional note.
• Persist expenses to expenses.json and load them back — including surviving a missing or corrupt file (start fresh rather than crash).
• Report: total spent, count of expenses, per-category totals (rounded to 2 decimals), and the top category (ties → the category that reached its total first).
• Budget guard: given a monthly budget, the report states remaining budget and warns when spending exceeds 90% of it.

Acceptance criteria (the graded core)

The functions below are graded on this page and in the readiness checkpoint — they are the contract your CLI is built on:

• add_expense(expenses, amount, category, note="") — validates, returns a NEW list (never mutates the input).
• category_report(expenses) — dict category → total, rounded.
• finance_summary(expenses, budget) — the full report dict.

Explicitly YOUR decisions

File layout, function names beyond the contract, the menu text, how notes are displayed, extra features (recurring expenses? export?), and how you test. The milestones on the next page suggest an order — they do not prescribe code.