quartermaster

Household budget tracker. FastAPI + HTMX frontend, SQLite backend.

Sections

The budget page shows one card per section. Every section accepts a name and amount per entry and displays a running total, except Primary Debt Target, which is a pointer to one of the Debt Minimums rows.

• Incomes
• Fixed Amount Bills
• Debt Minimums
• Primary Debt Target (pointer)
• Food and Essentials
• Subscriptions
• Other

Requirements

• Python 3.12+
• uv for dependency management

Setup

uv sync
uv run alembic upgrade head

The SQLite file lives at ./quartermaster.db by default. Override with the QUARTERMASTER_DB_URL environment variable (any SQLAlchemy URL).

Run

uv run uvicorn quartermaster.main:app --reload

Open http://127.0.0.1:8000.

Tests

uv run pytest

Tests run against an in-memory SQLite database; no migration step needed.

Backups

The SQLite data file is precious and gitignored. Before any schema change or destructive operation, back it up:

./scripts/backup-db.sh <reason>

Backups land next to the database in ./backups/ by default (QUARTERMASTER_BACKUP_DIR=/some/path to override) as quartermaster-YYYYMMDD-HHMMSS-{slug}.db using SQLite's online backup API (safe even while the app is writing). Alembic invokes the script automatically before every migration via alembic/env.py; retention is forever for now. To restore, stop the app, copy the chosen backup over quartermaster.db, and restart.

Project Layout

src/quartermaster/
  main.py         FastAPI app factory
  routes.py       HTTP handlers, HTMX partials
  service.py      Queries, totals, target logic
  models.py       SQLAlchemy models and Section enum
  db.py           Engine, session, PRAGMA foreign_keys=ON
  config.py       DB URL resolution
  templates/      Jinja2 templates (base, index, partials)
  static/         CSS
alembic/          Migrations
tests/            pytest suite

Scope

Single-month budget. Multi-month support is planned for a later milestone and is intentionally not modelled yet.