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.

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.