# 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 friendly, pastel-colored UI inspired by a clean spreadsheet aesthetic. 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: v1.1 Usability and Templates

**Goal:** Make the app actually usable for monthly budgeting — replace the manual copy workflow with a smart template system (fixed/variable/one-off items), add a quick-add library for recurring one-offs, and rethink the dashboard layout for dense, spreadsheet-like data presentation on desktop.

**Target features:**
- Budget template system with three item tiers (fixed, variable, one-off)
- Auto-generate new month budgets from template on navigate
- Quick-add library for saved one-off expense categories with icons
- Dashboard layout rethink — flatter, denser, less card chrome, more spreadsheet feel
- Desktop-optimized data density

## Requirements

### Validated

<!-- Shipped and confirmed valuable. -->

- ✓ Local auth (email/password registration, login, logout, JWT sessions) — v1.0
- ✓ Budget CRUD (create, edit, delete monthly budgets) — v1.0
- ✓ Budget item management (create, update, delete items per budget) — v1.0
- ✓ Category CRUD (bill, variable_expense, debt, saving, investment, income types) — v1.0
- ✓ Copy budget from previous month — v1.0 (being replaced by templates in v1.1)
- ✓ Server-side budget totals computation — v1.0
- ✓ REST API with auth middleware — v1.0
- ✓ i18n support (German + English, user preference stored) — v1.0
- ✓ Docker deployment (single binary, multi-stage build, compose) — v1.0
- ✓ Dashboard with financial overview, bills tracker, variable expenses, expense breakdown, debt tracker — v1.0
- ✓ Pastel design system with oklch tokens and semantic category colors — v1.0
- ✓ Branded auth screens, sidebar, and navigation — v1.0
- ✓ Interaction quality: spinners, inline edit affordances, row flash, delete confirmations — v1.0
- ✓ Empty states, loading skeletons, chart tooltips, locale-aware currency formatting — v1.0

### Active

<!-- Current scope. Template system + layout rethink. -->

- [ ] Budget template system — users define fixed and variable items that carry forward each month
- [ ] Fixed items auto-copied with amounts; variable items copied as category only (amount blank)
- [ ] One-off items added manually per month, not carried forward
- [ ] Auto-generate budget from template when navigating to a month with no budget
- [ ] Quick-add library — saved one-off categories with icons for reuse
- [ ] Replace "copy from previous month" with template-based generation
- [ ] Template management page — add/remove/reorder fixed and variable items
- [ ] Inline tagging of items as fixed/variable/one-off when adding
- [ ] Dashboard layout rethink — move away from heavy card containers toward flatter, integrated layout
- [ ] Increase data density — tighter rows, less padding, more visible without scrolling
- [ ] Fix card top padding above colored headers
- [ ] Desktop-optimized layout (web desktop is the primary target)

### Out of Scope

- CSV/bank import — future feature
- Shared/household budgets — future feature
- Custom themes/color picker — architecture supports it, not this milestone
- OIDC authentication — stubs exist, implement later
- PDF/CSV export — future feature
- Mobile app — web desktop is the focus
- GraphQL API — REST is sufficient
- Dark mode — light mode pastel system first
- Tablet/mobile responsiveness — desktop only for now

## Context

v1.0 shipped the visual identity — pastel oklch tokens, branded auth screens, sidebar, interaction quality (spinners, flash feedback, delete confirmations), empty states, chart tooltips, and locale-aware formatting. The app looks good but the UX for actually managing a monthly budget is clunky. The "copy from previous month" feature is a blunt instrument — it copies everything including one-off expenses. Users need a smarter template system that understands which expenses are fixed (rent), which recur but vary (groceries), and which are one-time (pharmacy visit). Additionally, the dashboard layout uses heavy card containers with excessive padding — it needs to lean more into the spreadsheet aesthetic with denser data presentation and less visual chrome. Desktop web is the primary and only target.

## 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
- **Backend**: Template system requires backend changes (new tables, API endpoints)
- **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 |
|----------|-----------|---------|
| Customize shadcn via CSS variables | Maintain upgrade path while achieving unique look | ✓ Good |
| Pastel palette as primary design language | Matches original spreadsheet inspiration | ✓ Good |
| Desktop-first responsive | Primary use case is desktop budget management | ✓ Good |
| Three-tier item model (fixed/variable/one-off) | Matches how users think about recurring vs one-time expenses | — Pending |
| Replace copy-from-previous with templates | Templates are smarter — copy was too blunt, carried one-offs forward | — Pending |
| Auto-generate budget on navigate | Removes friction — user just navigates to a month and it's ready | — Pending |
| Rethink cards as flatter containers | Current card chrome is too heavy — denser, spreadsheet-like layout | — Pending |

---
*Last updated: 2026-03-12 after v1.1 milestone start*