archeious 94e1571a3f docs: expand README with setup, run, tests, and layout

Refs #1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-17 11:04:21 -06:00

1.5 KiB

Raw Blame History

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.

1.5 KiB Raw Blame History