https://github.com/mgrimace/budget-overview
A visual budgeting tool that shows an overview of where your money goes each month using a Sankey-style flow diagram.
https://github.com/mgrimace/budget-overview
budget budget-app budgeting docker family minimal money-manager rust self-host
Last synced: 17 days ago
JSON representation
A visual budgeting tool that shows an overview of where your money goes each month using a Sankey-style flow diagram.
- Host: GitHub
- URL: https://github.com/mgrimace/budget-overview
- Owner: mgrimace
- License: agpl-3.0
- Created: 2026-03-15T19:10:48.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T14:17:31.000Z (2 months ago)
- Last Synced: 2026-03-30T15:27:26.218Z (2 months ago)
- Topics: budget, budget-app, budgeting, docker, family, minimal, money-manager, rust, self-host
- Language: TypeScript
- Homepage:
- Size: 990 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 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`:
```yaml
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:
```bash
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:
[](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=R4QX73RWYB3ZA)
[](https://liberapay.com/cammarata.m/)
[](https://www.ko-fi.com/mgrimace)
[](https://www.buymeacoffee.com/cammaratam)