Skip to content

Plan: Finances hub large refactor + modern refresh + big-player features

URL: https://mkdocs.justinsforge.com/memory/plans/finances-hub-refactor-redesign-2026-06-10/

Date: 2026-06-10 Approved spec: Split forge_finances_app.py (6,082 lines) into flat per-page blueprint modules plus a shared base (design system) and data-accessor module; thin entry keeps the same filename so forge-finances.service is untouched. Modern visual refresh keeps the dark Rocket-Money palette but upgrades typography, spacing, card depth, micro-interactions, and mobile. New features: Cash Flow page (income vs spend, upcoming-bills forecast, safe-to-spend), real Budgets (per-category targets, progress, left-to-spend), Net Worth pro (1M/3M/6M/1Y/ALL ranges, asset/debt class groups, per-account sparklines), Transactions power tools (filter bar, bulk edit, rules manager). Zero finance.db schema changes; every txn query filters COALESCE(superseded,0)=0; engine scripts untouched except additive reads. Backup at /home/justinwieb/forge-backups/finances-20260609-231319/. Out of scope: goals tracking, tax/report exports, PWA/offline, Google Sheet mirror write-back, multi-year history import, ERPNext-side work, any finance.db schema change.

Architecture

forge_finances_app.py          thin entry: Flask app, blueprint registration, /health, /sync, favicons
forge_finances_ui_base.py      design system: BASE shell/CSS/JS, NAV_ITEMS, ICONS, _esc/_money/_icon,
                               pills, chart builders (_donut/_smooth/_spend_chart/_period_bar_chart),
                               sidecar JSON load/save helpers
forge_finances_ui_icons.py     account/merchant logo + icon subsystem (cache, domain guess, panels, routes)
forge_finances_ui_data.py      shared read accessors (spend_overview, account_summary, month helpers,
                               recent_transactions, _latest_value), all superseded=0-audited
forge_finances_ui_dashboard.py /
forge_finances_ui_recurring.py /recurring + 20 sub-routes
forge_finances_ui_spending.py  /spending
forge_finances_ui_budget.py    /budget + set/bucket/autoset + budget engine v2
forge_finances_ui_accounts.py  /accounts, /account/<id> + value/nickname posts
forge_finances_ui_transactions.py /transactions, /transaction/<id>, setcat/edit + filter bar/bulk/rules
forge_finances_ui_networth.py  /networth + ranges/classes/sparklines
forge_finances_ui_cashflow.py  NEW /cashflow
forge_finances_ui_categorize.py /categorize + rule routes
forge_finances_ui_alerts.py    /alerts

Cutover safety: after every task, restart forge-finances.service and curl -fsS every GET route; forge_finances_js_check.py guards inline JS.

Task list

Task 1: Extract shared base module

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_base.py (new), /home/justinwieb/forge/scripts/forge_finances_app.py
  • What: Move shell()/BASE template/CSS/JS, NAV_ITEMS, ICONS, _icon/_esc/_money/_money0/_greeting/_smooth/_kfmt, _tx_pills, scope label maps, chart builders, and sidecar JSON helpers into the base module verbatim. App imports them.
  • Verification: systemctl restart forge-finances && curl -fsS http://127.0.0.1:8096/health && curl -fsS -o /dev/null -w '%{http_code}' http://127.0.0.1:8096/
  • Commit: finances: extract shared UI base module

Task 2: Extract icon/logo subsystem

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_icons.py (new), forge_finances_app.py
  • What: Move logo cache, domain guessing, _logo/_acct_icon/_merchant_*, icon panels, and the icon/logo routes (/account/<id>/icon*, /merchant/icon*, /icon-lib-search, /logo-search, /finance-icon/<fn>) into a blueprint.
  • Verification: curl -fsS 'http://127.0.0.1:8096/icon-lib-search?q=chase' | head -c 200
  • Commit: finances: extract icon/logo subsystem blueprint

Task 3: Extract shared data accessors with superseded audit

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_data.py (new), forge_finances_app.py
  • What: Move spend_overview, account_summary, recent_transactions, _latest_value, _categorize, month helpers. Audit every SQL string in the new module for COALESCE(superseded,0)=0 on transactions.
  • Verification: python3 -c "import sys; sys.path.insert(0,'/home/justinwieb/forge/scripts'); import forge_finances_ui_data as dd; print(dd.spend_overview()['total'] is not None)"
  • Commit: finances: extract shared data accessors

Task 4: Blueprint the dashboard

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_dashboard.py (new), forge_finances_app.py
  • What: Move / page into its own blueprint module.
  • Verification: route sweep script (all GETs 200)
  • Commit: finances: dashboard blueprint

Task 5: Blueprint recurring

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_recurring.py (new), forge_finances_app.py
  • What: Move /recurring + its ~20 sub-routes and helpers (_rec_*, excludes/types/fixed/flags sidecars).
  • Verification: route sweep + curl -fsS http://127.0.0.1:8096/recurring | grep -c card
  • Commit: finances: recurring blueprint

Task 6: Blueprint spending, accounts, alerts, categorize

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_spending.py, forge_finances_ui_accounts.py, forge_finances_ui_alerts.py, forge_finances_ui_categorize.py (new), forge_finances_app.py
  • What: Move /spending, /accounts + /account/<id> + posts, /alerts, /categorize + rule routes.
  • Verification: route sweep
  • Commit: finances: spending/accounts/alerts/categorize blueprints

Task 7: Blueprint transactions + networth + budget; thin entry

  • Files: forge_finances_ui_transactions.py, forge_finances_ui_networth.py, forge_finances_ui_budget.py (new), forge_finances_app.py
  • What: Move remaining pages. App file shrinks to entry + /sync + /health + favicons + blueprint registration.
  • Verification: route sweep; wc -l forge_finances_app.py < 300
  • Commit: finances: complete blueprint split, thin entry

Task 8: Modern refresh of the design system

  • Files: forge_finances_ui_base.py
  • What: Same palette vars, upgraded type scale (Inter/system stack, tabular numerals for money), tighter spacing rhythm, card elevation + hover states, animated number/chart transitions, skeleton-free fast paints, refined mobile nav (bottom bar under 860px), focus states.
  • Verification: /screenshot desktop+mobile of /, /networth, /recurring; visual check
  • Commit: finances: modern design refresh

Task 9: Net Worth pro

  • Files: forge_finances_ui_networth.py, forge_finances_ui_data.py
  • What: 1M/3M/6M/1Y/ALL range toggle on the history chart (weekly_snapshots, 614 rows back to 2023-05-29), Assets vs Debt class groupings with subtotals, per-account sparklines + period-change badges from balances/snapshots.
  • Verification: curl -fsS 'http://127.0.0.1:8096/networth?range=1y' | grep -c spark
  • Commit: finances: net worth ranges, class groups, sparklines

Task 10: Cash Flow page

  • Files: /home/justinwieb/forge/scripts/forge_finances_ui_cashflow.py (new), forge_finances_ui_base.py (NAV item), forge_finances_app.py (register)
  • What: /cashflow: monthly income vs spend paired bars (12mo), this-month net flow, upcoming recurring bills (next 30d) vs liquid balances, safe-to-spend = liquid minus upcoming bills minus budget remainder.
  • Verification: curl -fsS http://127.0.0.1:8096/cashflow | grep -ci 'safe to spend'
  • Commit: finances: cash flow + safe-to-spend page

Task 11: Budgets v2

  • Files: forge_finances_ui_budget.py, data/finance/budget_buckets.json (data, gitignored)
  • What: Per-category monthly targets with progress bars, left-to-spend hero, over-budget highlighting, prior-month compare, auto-suggest targets from 3-month averages. Storage stays in the JSON sidecar.
  • Verification: curl -fsS http://127.0.0.1:8096/budget | grep -c progress
  • Commit: finances: budgets v2

Task 12: Transactions power tools

  • Files: forge_finances_ui_transactions.py
  • What: Rocket-style top filter bar (date range, category, account, scope, amount min/max, search), bulk-select + bulk category/scope/ignore actions, rules manager drawer over user_categorization_rules.json.
  • Verification: curl -fsS 'http://127.0.0.1:8096/transactions?cat=Dining&min=10' | grep -c tx
  • Commit: finances: transaction filter bar, bulk edit, rules manager

Task 13: Register and document

  • Files: /home/justinwieb/forge/memory/general/reference_finances_app.md, MEMORY.md index, data/finance/COORDINATION.md
  • What: Update reference topic file with new module map + features, refresh MEMORY.md line, append a COORDINATION.md message documenting the UI-layer split (no schema/engine changes). Run eval.
  • Verification: bash /home/justinwieb/forge/scripts/forge_eval_run.sh
  • Commit: finances: register refactor + docs

[Claude Code, 2026-06-10]