zBudget

A self-hosted personal budgeting application with a clean dark/light UI, transaction tracking, category management, and budget monitoring. Runs entirely in Docker — no cloud account required.

---

Features

• Dashboard — Monthly spending summary, income vs. expense area chart, spending-by-category pie chart, budget health progress bars, and recent transactions at a glance
• Transactions — Add expenses or income with an Expense/Income toggle (no negative numbers needed), search and filter by type/date/category, inline category assignment, CSV export, and OFX/CSV import from bank statements
• Budgets — Create monthly or custom-date budgets per category, track spending against each budget with progress bars and colour-coded health indicators
• Categories — Create custom spending categories with descriptions, or seed a set of sensible defaults (Housing, Food & Dining, Transport, Health, etc.) with one click
• Dark / Light mode — Toggle between dark and light themes; preference is saved in the browser
• Multi-user — Each user's transactions and budgets are isolated; register as many accounts as needed

---

Tech Stack

Layer	Technology
Frontend	React 19 + TypeScript, Tailwind CSS v4, Zustand, Recharts
Backend	FastAPI (Python 3.11), SQLAlchemy 2, python-jose JWT
Database	PostgreSQL 15
Packaging	Docker + Docker Compose

---

Quick Start (Docker)

Prerequisites

• Docker and Docker Compose installed
• Port 3000 (frontend) and 8000 (API) available on your host

1. Clone the repository

git clone https://codevault.sh/zypher-systems/zbudget.git
cd zbudget

2. Create your environment file

cp .env.example .env

Open .env and set your values:

# Strong password for the PostgreSQL database
DATABASE_PASSWORD=change_me_strong_password

# Random secret used to sign JWT tokens — generate one with:
#   python3 -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=change_me_generate_a_random_secret_key

# Origin(s) the browser will connect from (adjust if running on a server)
ALLOWED_ORIGINS=http://localhost:3000

Security note: Never commit your .env file. It is already listed in .gitignore.

3. Build and start

docker compose up -d --build

This builds the backend and frontend images, starts PostgreSQL, and launches all three containers. First build takes a couple of minutes; subsequent starts are near-instant.

4. Open the app

Navigate to http://localhost:3000 in your browser.

Register a new account and you're ready to go. Use the Categories → Seed Defaults button to populate common spending categories instantly.

---

Deploying on a Server

To run on a remote server (VPS, home server, etc.):

1. Clone and configure .env as above, setting ALLOWED_ORIGINS to your server's URL:

   ALLOWED_ORIGINS=https://budget.yourdomain.com
   

2. If you want to expose the app on port 80/443, place a reverse proxy (nginx, Caddy, Traefik) in front of port 3000.

3. Run docker compose up -d --build.

---

Container Overview

Container	Image	Default Port	Purpose
zbudget-frontend	Built from frontend/	3000	Nginx serving the React SPA; proxies /api calls to the backend
zbudget-app	Built from backend/	8000	FastAPI REST API
zbudget-db	postgres:15-alpine	5432	PostgreSQL database (data persisted in a named Docker volume)

---

Useful Commands

# Start all containers in the background
docker compose up -d

# Stop all containers
docker compose down

# View live logs
docker compose logs -f

# View backend logs only
docker compose logs -f app

# Rebuild after code changes
docker compose build && docker compose up -d --force-recreate

# Open a PostgreSQL shell
docker exec -it zbudget-db psql -U zbudget_user -d zbudget

---

Using the App

Registering & Logging In

• Visit http://localhost:3000 and click Create one free to register
• Log in with your username and password
• Each user's data is fully isolated from other accounts

Categories

Before adding transactions or budgets, set up categories:

1. Go to Categories in the sidebar
2. Click Seed Defaults to add a standard set of categories automatically, or click + New Category to create your own
3. Categories can be edited or deleted at any time (deleting a category leaves existing transactions uncategorized)

Transactions

• Click + Add Transaction to open the form
• Choose Expense (red) or Income (green) — the sign is applied automatically
• Enter the amount, date, category, payee, and an optional memo
• Use the search bar to find transactions by payee or memo
• Use the filter row to show only expenses, only credits, or filter by date range
• Click Export CSV to download all visible transactions as a spreadsheet
• Click Import to bulk-import transactions from an OFX or CSV bank export file

Budgets

1. Go to Budgets and click + New Budget
2. Enter a name, choose a category, set the budget amount, and optionally set start/end dates
3. The budget card shows how much of the budget has been spent, colour-coded (green → amber → red)

Dashboard

The dashboard auto-refreshes on load and shows:

• Total spending, total income, and net balance for the current month
• A spending over time area chart (last 6 months)
• A spending by category pie chart
• A budget health summary for all active budgets
• The 5 most recent transactions

Dark / Light Mode

Click the sun/moon icon at the bottom of the sidebar to toggle themes. The preference is stored in your browser's local storage.

---

Data & Privacy

All data is stored locally in the PostgreSQL container volume (postgres_data). Nothing is sent to any external service. To back up your data:

docker exec zbudget-db pg_dump -U zbudget_user zbudget > backup.sql

To restore:

cat backup.sql | docker exec -i zbudget-db psql -U zbudget_user -d zbudget

---

License

MIT