SSBudget

A personal budget tracker built to answer one question: "How much can I spend this month?"

The Problem

Traditional budget apps obsess over categories and past spending. SSBudget focuses on the future.

SSBudget takes a different approach:

• Define your planned items — the fixed expenses (rent, bills), incomes and savings top-ups you expect this period
• Let category budgets derive your variable spend (groceries, fuel) from real bank transactions
• Update account balances and mark previously planned payments throughout the period
• Get your remaining free cash — your budget until the next paycheck

demo.webm

Additional Features

• Multi-currency — PLN, EUR, USD + 30 more with live exchange rates
• Passkey auth — Passwordless login, no user management needed
• Import/Export — You can take your whole database with you (god bless SQLite!)
• Spreadsheet-like UI — Edit in place, minimal clicks, maximum density
• Self-hosted — You can run it yourself anywhere.
• E2E test coverage — Everything important is covered with e2e selenium test.
• WhatsApp notification - So that you can proactively share your budget with your spouse.

Built With Claude

This project was 100% vibe-coded using Claude Code over 8 sessions (~4 days). The entire codebase — backend, frontend, database schema, tests, deployment config — was generated through conversation with Claude Opus/Sonnet.

Check docs/sessions/ for the session logs and CLAUDE.md for the context file that guided development.

Tech Stack

Layer	Stack
Language	Scala 3 (JVM + Scala.js)
Backend	cats-effect, http4s, tapir, doobie
Frontend	Laminar (Scala.js SPA), Bootstrap 5
Database	SQLite + Flyway migrations
Auth	WebAuthn passkeys + Argon2 password
Build	sbt, Vite

Quick Start

Prerequisites

• JDK 21+
• sbt 1.9+
• Node.js 18+

Development (3 terminals)

# Terminal 1: Scala.js watch
sbt '~frontend/fastLinkJS'

# Terminal 2: Vite dev server
cd frontend && npm install && npm run dev

# Terminal 3: Backend
sbt backend/run

Open http://localhost:3000. First visit prompts password setup.

Production Build

./build.sh              # Builds backend + frontend + Docker image (Metabase bundled)
docker run -p 8080:8080 -v ./data:/data ssbudget

The image includes the Metabase that powers the Analytics page, and the container starts and configures it on its own. Use ./build.sh --no-analytics for an app-only image (~630MB smaller, runs in 512MB). See docs/metabase-analytics.md.

Environment Variables

Variable	Default	Description
SSBUDGET_DB_PATH	data/ssbudget.db	SQLite database path
SSBUDGET_PORT	8080	Server port
SSBUDGET_RP_ID	localhost	WebAuthn relying party ID
SSBUDGET_RP_ORIGINS	http://localhost:3000,http://localhost:8080	Allowed origins

Deployment

See fly.toml for a fly.io deployment example. Key points:

• Persistent volume for SQLite
• Secrets for SSBUDGET_RP_ID and SSBUDGET_RP_ORIGINS
• shared-cpu-2x:2048MB, since the container runs the app and Metabase side by side

Project Structure

ssbudget/
├── shared/     # Cross-compiled models and API definitions
├── backend/    # http4s server, repositories, auth
├── frontend/   # Laminar SPA
├── e2e/        # Selenium tests
└── docs/       # Session logs