Budget - grumnuts/dosh GitHub Wiki
Budget
The Budget page is the heart of Dosh. It shows your current week's budget across all groups and categories, with how much you've spent and what's left.
Zero-Based Budgeting
Every dollar of income is assigned to a category. The goal is for:
Total Income Budgeted = Total Expenses Budgeted
The footer row shows Unallocated income — the difference between budgeted income and budgeted expenses for the week. Aim to get this to zero.
Budget Periods
Each category has its own period, independent of the weekly budget view:
| Period | Resets |
|---|---|
| Weekly | Every Sunday (or Monday, depending on your week start setting) |
| Fortnightly | Every two weeks |
| Monthly | 1st of each month |
| Quarterly | Every three months (Jan, Apr, Jul, Oct) |
| Annually | 1st of January |
The budget view always shows the current week, but each category's Spent and Balance reflect its own period — not just the current week.
For example, a monthly "Groceries" category set to $600 shows cumulative spending for the entire calendar month, even when you're viewing an earlier or later week within that month.
Columns
| Column | Description |
|---|---|
| Category | The category name, with its period shown as a badge |
| Budgeted | The amount set for this category's period |
| Weekly | Weekly equivalent amount (see below) |
| Spent | Transactions assigned to this category within the current period |
| Balance | Budgeted - Spent + Covers |
Groups
Categories are organised into groups (e.g. "Living Expenses", "Savings Goals", "Income"). Groups can be:
- Created, renamed, and deleted
- Reordered by dragging on desktop
- Collapsed and expanded by clicking the group row
- Marked as Income groups — income categories are shown separately and factor into the unallocated income footer calculation
To edit a group on desktop, use the edit button that appears on the right of the group row on hover. On mobile, long-press the group row (hold for 1 second) to open the group editor.
Debt Payments
The Debt Payments section is a special group created and managed automatically. When you create a Debt account, a matching category appears here. These categories cannot be renamed or deleted from the Budget page — they are controlled by their corresponding account. See Debt Budget Categories for details.
Savings & Investments
The Savings & Investments section appears at the bottom of the budget page. It consolidates savings accounts and investment categories into a single view:
- Savings accounts — each savings account appears as a row showing its current balance and any budgeted contribution for the period
- Investment categories — categories marked as investments (with a ticker) appear here, showing budgeted contribution, amount spent (i.e. invested), and remaining balance
This section is read-only; to edit a category, click its name to open the category editor.
Covers
When a category goes overspent (balance < 0), you can cover it from a savings account using a cover transfer. Click the red balance to open the Cover modal. On mobile, long-press the category row or tap the Cover button in the category editor.
A cover moves money from a savings account to zero out the overspend. The cover is tagged to the specific week so that historical budget views remain accurate.
A category can be covered multiple times — each cover zeroes the current overspend at the time.
Sweep to Savings
When a category has a positive balance (unspent budget), you can sweep the surplus to a savings account. On desktop, hover over a category row and click the Sweep button. On mobile, tap the category row to open the editor and tap Sweep.
The sweep modal lets you:
- Enter the amount to sweep (defaults to the full available balance)
- Choose which spending account to transfer from
- Choose which savings account to receive the funds
The sweep reduces the category balance by the swept amount, and both transactions appear in the transaction list for matching when you import your next CSV.
Balance formula:
Balance = Budgeted - Spent + Covers - Sweeps
Budget History
When you change a category's budgeted amount, the change takes effect from the current week. Historical weeks retain the amount that was set at the time — so past views are always accurate.
Category Settings
Click a category name to open its edit modal:
- Name
- Amount — dollars budgeted per period
- Period — weekly / fortnightly / monthly / quarterly / annually
- Notes — optional memo shown in the modal
- Catch up — see below
- Investment category — marks this category as an investment; enables the ticker field and quantity field on transactions
- Ticker — the ticker symbol for the investment instrument (e.g.
VAS.AX,AAPL). When set, all transactions in this category automatically use this ticker — no need to enter it per transaction - Archive — hides the category from the budget view (transactions are retained)
Reordering
On desktop, drag the handle on the left of any group or category row to reorder it. Order is saved to the server immediately.
Weekly Equivalent
Each category shows a Weekly column. For non-weekly categories, this is a proportional estimate of the weekly cost — used for planning purposes only. It has no effect on balance or overspend calculations.
| Period | Weekly Equivalent |
|---|---|
| Weekly | Budgeted amount |
| Fortnightly | ⌈Budgeted ÷ 2⌉ |
| Monthly | ⌈Budgeted × 12 ÷ 52⌉ |
| Quarterly | ⌈Budgeted × 4 ÷ 52⌉ |
| Annually | ⌈Budgeted ÷ 52⌉ |
Fractional cents are always rounded up.
Catch-up
Each category has an optional Catch up toggle. When enabled, the weekly equivalent is recalculated dynamically from the most recent budget change to the end of the current period:
Weekly equivalent = ⌈Budgeted amount ÷ weeks remaining from last budget change⌉
Example: It's week 3 of a monthly period and you increase a category's budget from $200 to $300. With catch-up off, the weekly equivalent stays at the standard $300 × 12 ÷ 52 = ~$69. With catch-up on, it divides $300 across the remaining 2 weeks of the month, giving $150/week — reflecting how much you actually need to set aside each remaining week.
Catch-up only affects the Weekly column. It has no effect on the Balance or Spent columns, which always use the full budgeted amount over the category's own period.
Tip: Catch-up is most useful for long-period categories (monthly, quarterly, annual) when you adjust the budget partway through a period and want the weekly planning figure to stay accurate.
Mobile
On mobile, the Budget page is optimised for smaller screens:
- A floating action button (FAB) in the bottom-right corner expands to reveal speed dial options for adding a group or category
- Week navigation is anchored in a fixed bar above the bottom nav — tap the week label (e.g. "Week 15") to jump back to the current week; the current week is highlighted in green
- Swipe left or right on the budget page to navigate between weeks
- The Spent column (expense groups) and Outstanding column (debt groups) are hidden to maximise space for category names
- Long-press a group row (hold for 1 second) to open the group editor; a quick tap collapses or expands the group