Budget Overview

I made this to replace my family's Excel spreadsheet. It's a simple monthly budget planner with a clear visual overview of money in and money out, and what's left (or in deficit) afterwards.

Note

This is still in active development, please be patient

Screenshot

Light mode	Dark mode

Tip

Theme support added as of v0.9.5, with Nord, Everforest, Gruvbox, and more!

Features

• Sankey diagram — visualise your full budget as a flow from income through expenses to remaining or deficit, updates live as items are added
• Recurring items — enter income and expenses at any frequency, everything normalises to monthly automatically
• Variable amounts — month-by-month overrides for things that change, like utilities
• Tags and reports — tag items and filter the summary view, handy for things like home office expenses at tax time
• Upcoming bills — sidebar showing what's due this month in date order
• Self-hosted — Run it yourself, your financial data is yours
• Dark mode — full light and dark theme
• PWA — installable on desktop and mobile, works offline

Note

I built this with WCAG 2.2 AA in mind, though there's still plenty of work to do for accessibility.

What it's not

It's not a transaction tracker or accounting software. No bank sync, no receipt scanning, no daily logging. It's for setting up your monthly budget picture and understanding it visually.

The project is intentionally simple, and it is not designed for enterprise use.

Tech Stack

• Frontend — React, TypeScript, Vite
• Backend — Rust, Axum
• Database — SQLite
• Visualisation — @nivo/sankey
• Icons — Phosphor React
• Font — Atkinson Hyperlegible

Quick Start

Create a docker-compose.yml:

services:
  app:
    container_name: budget-overview
    image: ghcr.io/mgrimace/budget-overview:latest
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      DATABASE_PATH: /app/data/budget.db
    restart: unless-stopped

Then run:

docker compose up -d

Open http://localhost:3001. Data persists to ./data/budget.db.

API Endpoints

Method	Path	Description
GET	/api/budget-items	List all budget items
POST	/api/budget-items	Create a budget item
GET	/api/budget-items/:id	Get a budget item
PUT	/api/budget-items/:id	Update a budget item
DELETE	/api/budget-items/:id	Delete a budget item
GET	/api/tags	List all tags
POST	/api/tags	Create a tag
PUT	/api/tags/:id	Rename a tag
DELETE	/api/tags/:id	Delete a tag
GET	/api/cashflow	Get Sankey diagram data
GET	/api/upcoming-bills	Get upcoming bills
PATCH	/api/budget-items/:id/primary-tag	Set a budget item primary tag (adds to tags if needed)
PATCH	/api/budget-items/:id/visibility	Set a budget item visibility (true=show in Sankey, false=hide)

Normalization

All amounts are normalized to monthly values for display and calculation.

Frequency	Formula
Daily	amount × 30
Weekly	amount × 4.33
Biweekly	amount × 2.17
Monthly	amount
Yearly	amount ÷ 12

Variable bills (e.g. utilities with different amounts each month) are averaged across the months provided.

Default Tags

Housing, Utilities, Food, Transportation, Healthcare, Entertainment, Shopping, Travel, Subscriptions, Loans

Untagged expense items appear under Misc automatically.

Support

If you've found this project helpful and would like to support further development, please consider donating. Thank you: