SimpleFinanceDash

What This Is

A self-hosted personal budget dashboard that replaces a manual spreadsheet workflow. It tracks monthly budgets with bills, variable expenses, debts, savings, and investments — presented in a dense, visually rich UI with OKLCH pastel colors, three chart types (donut, bar, horizontal bar), collapsible category sections, and consistent design across all 9 pages. Features a smart template system for recurring items, quick-add library for one-off expenses, and auto-generated budgets. Built with Go (backend) + React/TypeScript (frontend) + PostgreSQL.

Core Value

Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product.

Current Milestone: v2.0 UX Simplification & Design Rework

Goal: Make the app intuitive and visually clean — template-driven budgeting with a sharp, minimal, pastel design system.

Target features:

Design system overhaul — sharp edges, clear pastels, minimal whitespace-driven layout
Wizard-style template setup with pre-filled common items (rent, car insurance, groceries, etc.)
Category library with smart defaults and sensible pre-loaded amounts
Auto-created monthly budgets from template on first visit (no prompts)
Simplified budget view — add one-offs from category library directly (replaces quick-add page)
Dashboard = this month's budget at a glance (not chart overload)
Dashboard data fixes — spending/budget data correctly reflects user input

Current State

Shipped: v1.0 (UI/UX Overhaul) + prior foundation (auth, CRUD, templates, quick-add)

The app has a visual overhaul but the UX is poor — too many disconnected concepts (categories, templates, budgets, quick-add), the design feels clunky with excessive rounding, and the dashboard doesn't clearly show budget data. v2.0 simplifies the mental model to two concepts: "my template" and "this month's budget."

Requirements

Validated

✓ User can sign up with email/password — existing
✓ User can log in with email/password — existing
✓ User can log in with Google or GitHub OAuth — existing
✓ User can sign out from any page — existing
✓ User can create and manage expense categories (income, bill, variable expense, debt, saving, investment) — existing
✓ User can set up a monthly budget template with fixed/variable items — existing
✓ User can generate monthly budgets from template — existing
✓ User can track budgeted vs actual amounts per category item — existing
✓ User can add items quickly via quick-add library — existing
✓ User can set locale and currency in settings — existing
✓ App supports English and German — existing
✓ Dashboard shows summary cards (income, expenses, balance) — existing
✓ UI-DASH-01: Redesign dashboard with hybrid layout — summary cards, charts, and collapsible category sections — v1.0
✓ UI-BAR-01: Bar chart comparing income budget vs actual — v1.0
✓ UI-HBAR-01: Horizontal bar chart comparing spend budget vs actual by category type — v1.0
✓ UI-DONUT-01: Improved donut chart for expense category breakdown with richer styling — v1.0
✓ UI-COLLAPSE-01: Collapsible inline sections on dashboard for each category group — v1.0
✓ UI-DESIGN-01: Redesigned all pages with rich, colorful visual style — v1.0
✓ UI-AUTH-01: Refreshed login and register pages — v1.0
✓ UI-CATEGORIES-01: Refreshed categories page — v1.0
✓ UI-TEMPLATE-01: Refreshed template page — v1.0
✓ UI-BUDGETS-01: Refreshed budget list and budget detail pages — v1.0
✓ UI-QUICKADD-01: Refreshed quick-add page — v1.0
✓ UI-SETTINGS-01: Refreshed settings page — v1.0
✓ UI-RESPONSIVE-01: Desktop-first responsive layout across all pages — v1.0

Active

Design system: sharp edges, clear pastels, minimal layout
Wizard-style template setup with smart defaults
Category library with pre-loaded common items
Auto-created monthly budgets from template
Simplified budget view with inline add-from-library
Dashboard shows current month's budget clearly
Dashboard data correctly reflects entered spending

Out of Scope

Recurring transaction automation — future feature
Spending alerts or notifications — future feature
Trend charts over months — future feature
Mobile-first optimization — desktop first, basic responsiveness only
CSV/bank import — future feature
Shared/household budgets — future feature
Dark mode — light mode pastel system first

Context

v1.0 shipped a visual overhaul but the UX remains problematic. The user model has too many disconnected concepts — categories, templates, budgets, and quick-add are all separate pages with unclear relationships. The design system has excessive rounding and colors that aren't truly pastel. The dashboard shows charts but doesn't clearly reflect budget data the user entered.

v2.0 simplifies to two user-facing concepts: "my template" (recurring budget structure with smart defaults) and "this month's budget" (auto-created from template, track actuals, add one-offs from library). The design shifts to sharp, minimal, clean pastels.

Tech stack: Go 1.25 + React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui + Recharts + PostgreSQL 16. Package manager: bun. Single Docker image via multi-stage build. Backend changes are in scope for this milestone where needed to support auto-creation and template-driven flow.

Constraints

Tech stack: Keep existing Go + React + shadcn/ui + Tailwind + Recharts stack
Design system: Build on shadcn/ui, customize via CSS variables and Tailwind config
i18n: All new/changed UI text must have de + en translations
Package manager: Use bun for frontend
Platform: Desktop web only — no mobile/tablet optimization

Key Decisions

Decision	Rationale	Outcome
UI overhaul only, no backend changes	Keep scope focused, ship faster, reduce risk	✓ Good
Desktop-first layout	Primary use case is desktop; basic responsive for mobile	✓ Good
Rich & colorful visual style	Match the visual density and appeal of the spreadsheet reference	✓ Good
Hybrid dashboard (summary + collapsible sections)	Best of both: quick overview with drill-down capability inline	✓ Good
All three chart types (bar, horizontal bar, donut)	Comprehensive financial visualization like the reference	✓ Good
Refresh all pages, not just dashboard	Consistent design language throughout the app	✓ Good
4-phase roadmap: Foundation > Charts > Collapsibles > Full-app	Design tokens before components, dashboard before other pages	✓ Good
URL-based month navigation via useMonthParam	Survives refresh and enables sharing; uses ?month=YYYY-MM search param	✓ Good
3-column responsive chart grid (md:2, lg:3)	Fits donut + 2 bar charts; collapses gracefully on smaller screens	✓ Good
DashboardContent as inner component pattern	Separates month selection/empty state from data-dependent chart rendering	✓ Good
Two-tier OKLCH category colors	Darker text (~0.55) for WCAG contrast, lighter fills (~0.65-0.70) for charts	✓ Good
CategorySection controlled open/onOpenChange pattern	Parent owns state for smart expand defaults and month-change reset	✓ Good
Auth card accent pattern (border-t-4 + favicon logo)	Consistent brand presence without heavy custom design	✓ Good
Direction-aware diff for all 6 category types	Spending over when actual > budget; income/saving over when actual < budget	✓ Good
Simplify to 2 user concepts: template + monthly budget	Categories/templates/budgets/quick-add too disconnected; users don't understand the flow	— Pending
Sharp minimal design with clear pastels	v1.0 rounded/clunky design doesn't match the "clean spreadsheet" vision	— Pending
Auto-create budgets from template on month visit	Removes friction; template is the source of truth	— Pending
Wizard-style template setup with smart defaults	First-run must be intuitive; pre-filled common items reduce setup time	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd:transition):

Requirements invalidated? → Move to Out of Scope with reason
Requirements validated? → Move to Validated with phase reference
New requirements emerged? → Add to Active
Decisions to log? → Add to Key Decisions
"What This Is" still accurate? → Update if drifted

After each milestone (via /gsd:complete-milestone):

Full review of all sections
Core Value check — still the right priority?
Audit Out of Scope — reasons still valid?
Update Context with current state

Last updated: 2026-04-02 after v2.0 milestone kickoff

8.9 KiB Raw Blame History