# Budget Phase 1 — Manual Budget Ledger Foundation

Use this reference when implementing the first productive Budget/Cashflow foundation inside FinanceManager after the PRD/source-analysis phase.

## Scope boundary

Budget Phase 1 is **manual ledger foundation only**:

- budget accounts linked optionally to existing portfolio `accounts`
- categories and tags with idempotent seeds
- manual income/expense transactions
- manual transfers
- monthly overview/read model
- Vue/FastAPI user flows with Preview → Confirm

Explicitly **out of scope** unless separately authorized:

- VISA CSV import
- Migros/Cumulus import
- rule engine
- duplicate engine
- productive importer writes
- forecasting/FIRE/analytics modules

## Data model pattern

Create an append-only migration with exact-money fields as `TEXT` where precision matters:

- `budget_accounts`
- `budget_categories`
- `budget_tags`
- `budget_transactions`
- `budget_transaction_tags`
- `budget_transfers`

Budget transactions should store:

- original amount/currency
- CHF amount when known/applicable
- `fx_status` (`not_needed`, `ok`, `missing`, `manual_override`, `estimated`)
- status (`draft`, `confirmed`, `reversed`, `archived`)
- source type (`manual`, later import-placeholder/system)
- optional reversal link

For CHF manual transactions, set FX status to `not_needed`. For foreign-currency entries with no local FX available, persist a reviewable `missing` state rather than inventing a rate.

## Service/API workflow

Follow the established FinanceManager write-boundary:

1. Preview endpoint/service validates and returns a proposed DTO but writes nothing.
2. Confirm endpoint/service performs the write and creates/audit-traces the domain change where the project has audit support.
3. Archive/reversal paths preserve history; avoid silent deletes.
4. Overview APIs read from local DB only.

Useful API groups:

- accounts: list, preview, confirm, archive
- categories/tags: list/tree, preview, confirm, archive
- transactions: list, preview manual transaction, confirm manual transaction
- transfers: preview, confirm
- overview: current-month income, expenses, net cashflow, review-needed, top categories, latest transactions

## Frontend pattern

For Vue User Mode:

- expose Budget under Planning/navigation as a real page, not a "later" placeholder
- provide compact pages for Overview, Transactions, Accounts, Categories
- make manual transaction and transfer forms explicit Preview → Confirm flows
- keep unfinished import/rule-engine controls absent or clearly roadmap-only; no fake buttons
- use mocks/tests that reflect API DTO shape changes

## Verification pattern

Run the full backend/frontend gate before committing:

```bash
python -m compileall src tests
PYTHONPATH=src pytest -q
cd frontend && npm test && npm run build
```

Then clean generated artifacts before Git-safety:

```bash
rm -rf .pytest_cache frontend/node_modules frontend/dist
find . -type d -name __pycache__ -prune -exec rm -rf {} +
```

Run Git-safety/diff checks and only then stage/commit/push. If normal `origin` push is unauthenticated but the FinanceManager GitHub token CSV exists outside the repo, use a temporary authenticated URL, verify remote hash equality, then unset secrets. Never persist token-bearing remotes or print token values.

## Pitfalls

- Do not let the Budget foundation quietly become an import sprint. Manual ledger first; imports need their own dry-run/review/duplicate/rule safety layer.
- Do not expose raw internal FX states in normal User Mode; translate them to user-facing labels/choices when building UI.
- Do not store Decimal-looking budget amounts in SQLite `NUMERIC`/`REAL` when exactness matters; use `TEXT` plus Decimal logic.
- Do not run Git-safety while generated `node_modules`, `dist`, `.pytest_cache`, or `__pycache__` still exist in the repo tree.