# Moon Household Budget

Personal household-budgeting web app for Tony & Bonna's household. Self-hosted
on the home NAS — single household, not a product. No billing, no multi-tenancy.

## Stack
- **Flask + gunicorn** (1 worker + threads — state lives in files on the volume,
  so multiple processes would race). Jinja templates all extend `base.html`.
- **Storage:** small data = JSON files via `storage.py` (atomic writes,
  crash-safe loads). **Transactions = SQLite** (`txns_db.py`, `transactions.db`)
  with the same list-of-dicts API as the old JSON.
- **Settings/secrets:** `/settings` page → `settings.py` → `settings.json` on the
  volume (never in git). `reminders.py` reads Gmail creds from there.
- **Suggestions (💡):** `suggestions/` blueprint files feedback as Gitea issues
  (needs `GITEA_URL/GITEA_TOKEN/GITEA_REPO` in `.env`).
- **Version chip + changelog:** `version.py` + `/changelog`, sourced from
  `changelog.json`.

## ⚠️ Release process — REQUIRED on every deploy
Every deploy MUST cut a release so users see what changed. Before deploying:

```sh
python release.py <version> "<plain-language change>" "<another change>" [--title "..."]
```

- Bump the **patch** (0.1.0 → 0.1.1) for fixes, the **minor** (0.1.0 → 0.2.0)
  for new features.
- Write changes in plain language Bonna will understand (not code-speak).
- This updates `changelog.json` (drives `__version__`, the footer chip, and
  `/changelog`) and regenerates `CHANGELOG.md`. Commit both with your change.
- **Do not deploy without a new changelog entry.**

## Deploy (Docker on Unraid NAS — http://192.168.0.5:8052)
```sh
# from the repo root, after committing (incl. the release entry):
rsync -a --exclude='.git/' --exclude='data/' --exclude='.env' --exclude='__pycache__/' \
  ./ root@192.168.0.5:/mnt/user/appdata/moon-household-budget/
ssh root@192.168.0.5 'cd /mnt/user/appdata/moon-household-budget && docker compose up -d --build'
```
- **Never** rsync `data/` or `.env` — that's live data and secrets on the volume.
- Templates are baked into the image, so template changes need `--build`.
- Backups: the `backup` sidecar tars `/data` to `/mnt/user/Backup/moon-household-budget/`
  daily; pushes to Backblaze B2 only once a real bucket/key is in `.env`.

## Conventions
- Secrets never go in source — use `.env` (container) or `settings.json` (volume).
- Keep other small JSON files as JSON; only `transactions` warranted SQLite.
- Repo lives on the home Gitea: `bonna61/Moon-Household-Budget`.