Moon-Household-Budget/CLAUDE.md

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:

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)

# 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.