# 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](https://github.com/astral-sh/uv) for dependency management

## Setup

```sh
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

```sh
uv run uvicorn quartermaster.main:app --reload
```

Open http://127.0.0.1:8000.

## Tests

```sh
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.