Initial scaffolding and single-month budget MVP #1

New issue

Closed

opened 2026-04-17 10:58:15 -06:00 by claude-code · 0 comments

claude-code commented

2026-04-17 10:58:15 -06:00

Collaborator

Goal

Stand up quartermaster with a working single-month budget view. Web UI, FastAPI + HTMX, SQLite backend. Multi-month support is explicitly out of scope for this issue.

Sections

Each section renders a list of entries (name + amount) and a total. All sections except "Primary Debt Target" accept user-added rows.

Incomes
Fixed Amount Bills
Debt Minimums
Primary Debt Target (display-only, sourced from a chosen Debt Minimums row)
Food and Essentials
Subscriptions
Other

Data Model

entry
  id            INTEGER PK
  section       TEXT NOT NULL   # enum: income, fixed_bill, debt_minimum, food, subscription, other
  name          TEXT NOT NULL
  amount        NUMERIC(10,2) NOT NULL
  created_at    TIMESTAMP
  updated_at    TIMESTAMP

debt_target                      # singleton (id always = 1)
  id                INTEGER PK CHECK (id = 1)
  debt_minimum_id   INTEGER NULL REFERENCES entry(id) ON DELETE SET NULL
  updated_at        TIMESTAMP

The target points to an existing debt_minimum row. Deleting that row clears the pointer via ON DELETE SET NULL.

Tech Stack

Matching the Archon project where sensible:

Python 3.12+, managed with uv
FastAPI + Jinja2 templates + HTMX for interactivity
SQLAlchemy 2.x + Alembic migrations
SQLite (file-based)
pytest for tests
uvicorn for local run

Acceptance Criteria

uv run uvicorn quartermaster.main:app serves the budget page
Each section shows its entries, a total, and (except Debt Target) an inline add form
Entries can be deleted
A Debt Minimums row can be selected as Primary Debt Target; the Debt Target card reflects the selection
Totals recompute via HTMX partial swaps, no full page reload
Alembic migration creates the initial schema
Pytest covers: CRUD per section, target selection, target cleared on deletion of the referenced debt minimum
README documents dev setup

Out of Scope

Multi-month budgets, history, carryover
Auth
Currency formatting beyond plain USD
CSV import/export
Any styling framework beyond basic CSS

## Goal Stand up quartermaster with a working single-month budget view. Web UI, FastAPI + HTMX, SQLite backend. Multi-month support is explicitly out of scope for this issue. ## Sections Each section renders a list of entries (name + amount) and a total. All sections except "Primary Debt Target" accept user-added rows. - Incomes - Fixed Amount Bills - Debt Minimums - Primary Debt Target (display-only, sourced from a chosen Debt Minimums row) - Food and Essentials - Subscriptions - Other ## Data Model ``` entry id INTEGER PK section TEXT NOT NULL # enum: income, fixed_bill, debt_minimum, food, subscription, other name TEXT NOT NULL amount NUMERIC(10,2) NOT NULL created_at TIMESTAMP updated_at TIMESTAMP debt_target # singleton (id always = 1) id INTEGER PK CHECK (id = 1) debt_minimum_id INTEGER NULL REFERENCES entry(id) ON DELETE SET NULL updated_at TIMESTAMP ``` The target points to an existing debt_minimum row. Deleting that row clears the pointer via ON DELETE SET NULL. ## Tech Stack Matching the Archon project where sensible: - Python 3.12+, managed with `uv` - FastAPI + Jinja2 templates + HTMX for interactivity - SQLAlchemy 2.x + Alembic migrations - SQLite (file-based) - pytest for tests - uvicorn for local run ## Acceptance Criteria - [ ] `uv run uvicorn quartermaster.main:app` serves the budget page - [ ] Each section shows its entries, a total, and (except Debt Target) an inline add form - [ ] Entries can be deleted - [ ] A Debt Minimums row can be selected as Primary Debt Target; the Debt Target card reflects the selection - [ ] Totals recompute via HTMX partial swaps, no full page reload - [ ] Alembic migration creates the initial schema - [ ] Pytest covers: CRUD per section, target selection, target cleared on deletion of the referenced debt minimum - [ ] README documents dev setup ## Out of Scope - Multi-month budgets, history, carryover - Auth - Currency formatting beyond plain USD - CSV import/export - Any styling framework beyond basic CSS