123 lines
7.4 KiB
Markdown
123 lines
7.4 KiB
Markdown
# 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 State
|
|
|
|
**Shipped:** v1.0 (UI/UX Overhaul) + prior foundation (auth, CRUD, templates, quick-add)
|
|
|
|
The app has a complete visual overhaul:
|
|
- OKLCH design system with two-tier category colors and semantic budget status tokens
|
|
- PageShell, StatCard, SummaryStrip shared components for consistent page structure
|
|
- Three chart types (expense donut, income bar, spend horizontal bar) with CSS variable theming
|
|
- URL-based month navigation with MonthNavigator dropdown
|
|
- Collapsible per-category dashboard sections with direction-aware diff and CSS animations
|
|
- All 9 pages upgraded with consistent design, skeleton loading, and i18n
|
|
- Auth pages redesigned with brand presence and OAuth icons
|
|
|
|
## 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
|
|
|
|
<!-- Next milestone scope. TBD. -->
|
|
|
|
(No active requirements — next milestone not yet planned)
|
|
|
|
### Out of Scope
|
|
|
|
- New backend features or data model changes — UI milestone complete, future milestones may add backend
|
|
- 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 (UI/UX Overhaul) shipped a complete visual transformation across all 9 pages. The design system uses OKLCH color tokens with a two-tier approach (darker text colors for WCAG contrast, lighter fills for charts). PageShell provides consistent page headers. Three chart types replace the old pie chart and progress bars. Collapsible category sections give users drill-down capability on the dashboard. All pages have skeleton loading states and full i18n coverage.
|
|
|
|
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.
|
|
|
|
## 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 |
|
|
|
|
## Evolution
|
|
|
|
This document evolves at phase transitions and milestone boundaries.
|
|
|
|
**After each phase transition** (via `/gsd:transition`):
|
|
1. Requirements invalidated? → Move to Out of Scope with reason
|
|
2. Requirements validated? → Move to Validated with phase reference
|
|
3. New requirements emerged? → Add to Active
|
|
4. Decisions to log? → Add to Key Decisions
|
|
5. "What This Is" still accurate? → Update if drifted
|
|
|
|
**After each milestone** (via `/gsd:complete-milestone`):
|
|
1. Full review of all sections
|
|
2. Core Value check — still the right priority?
|
|
3. Audit Out of Scope — reasons still valid?
|
|
4. Update Context with current state
|
|
|
|
---
|
|
*Last updated: 2026-03-24 after v1.0 UI/UX Overhaul milestone completion*
|