SimpleFinanceDash/PRD.md

SimpleFinanceDash - Product Requirements Document

1. Overview

SimpleFinanceDash is a self-hosted personal budget dashboard web application. It replaces a manual spreadsheet-based budget tracker with a proper application, enabling future extensibility (sharing, automations, summaries). The application replicates a monthly budget tracking workflow with support for bills, variable expenses, debts, savings, and investments.

2. Goals

• Provide a clean, pastel-themed budget dashboard that mirrors the existing spreadsheet workflow
• Self-hosted, lightweight single-binary deployment
• Support for German and English (i18n)
• Solid foundation for future features (sharing, automation, customization)

3. Users

• MVP: Single-user accounts, isolated data per user
• Future: Shared/household budgets, multi-user collaboration

4. Tech Stack

Layer	Technology
Frontend	React + Vite + TypeScript + Tailwind CSS + shadcn/ui
Backend	Go (standard library + router of choice)
Database	PostgreSQL
Auth	Local username/password + OIDC (e.g. Authentik)
Deployment	Single binary (embedded SPA) + Docker Compose
API	REST (JSON)

5. Architecture

5.1 Single Binary

The Go backend embeds the built React SPA using embed.FS. A single Docker image contains everything. PostgreSQL runs as a separate service in compose.yml.

5.2 Project Structure (proposed)

SimpleFinanceDash/
  backend/
    cmd/server/         # main entrypoint
    internal/
      api/              # HTTP handlers / routes
      auth/             # local auth + OIDC
      db/               # database access (queries, migrations)
      models/           # domain types
      i18n/             # translations
    migrations/         # SQL migration files
  frontend/
    src/
      components/       # React components (shadcn/ui based)
      pages/            # route-level pages
      hooks/            # custom hooks
      lib/              # utilities, API client
      i18n/             # translation files (de, en)
  compose.yml
  Dockerfile
  PRD.md

6. Data Model

6.1 Core Entities

User

• id (UUID)
• email
• password_hash (nullable, empty for OIDC-only users)
• oidc_subject (nullable)
• display_name
• preferred_locale (de | en)
• created_at, updated_at

Category

• id (UUID)
• user_id (FK)
• name
• type: enum(bill, variable_expense, debt, saving, investment, income)
• icon (optional, for future use)
• sort_order
• created_at, updated_at

Categories are global per user and reused across budget periods.

Budget

• id (UUID)
• user_id (FK)
• name (e.g. "Oktober 2025")
• start_date
• end_date
• currency (default: EUR)
• carryover_amount (manually set or pulled from previous budget)
• created_at, updated_at

BudgetItem

• id (UUID)
• budget_id (FK)
• category_id (FK)
• budgeted_amount (planned)
• actual_amount (spent/received)
• notes (optional)
• created_at, updated_at

Each BudgetItem represents one category's row within a monthly budget (e.g. "Strom & Heizung" with budget 65.00, actual 65.00).

6.2 Relationships

User 1--* Category
User 1--* Budget
Budget 1--* BudgetItem
Category 1--* BudgetItem

6.3 Derived Values (computed, not stored)

• Available amount = carryover + sum(income actuals) - sum(bill actuals) - sum(expense actuals) - sum(debt actuals) - sum(saving actuals) - sum(investment actuals)
• Budget vs Actual per type = aggregated from BudgetItems
• Remaining per category = budgeted - actual

7. Features (MVP)

7.1 Authentication

• Local auth: Email + password registration/login with bcrypt hashing
• OIDC: Connect to external identity providers (e.g. Authentik). Strongly encouraged over local auth in the UI
• Session management: HTTP-only cookies with JWT or server-side sessions

7.2 Budget Setup

• Create a new monthly budget period (start date, end date, currency, carryover)
• Option to copy categories/budgeted amounts from a previous month
• Edit or delete existing budgets

7.3 Dashboard View

Replicates the spreadsheet layout as a single-page dashboard for the selected budget:

Top Section - Financial Overview

• Carryover, Income, Bills, Expenses, Debts, Savings, Investments
• Budget vs Actual columns
• Available balance with donut chart

Bills Tracker

• Table of bill categories with Budget and Actual columns
• Inline editing of actual amounts

Variable Expenses Summary

• Table with Budget, Actual, Remaining columns
• Bar chart: Budget vs Actual per category

Expense Breakdown

• Pie chart showing distribution across expense categories

Debt Tracker

• Table of debt categories with Budget and Actual columns

7.4 Category Management

• CRUD for categories per user
• Category types: bill, variable_expense, debt, saving, investment, income
• Categories persist across budgets

7.5 Internationalization (i18n)

• German (de) and English (en)
• User preference stored in profile
• All UI labels, messages, and formatting (date, currency) localized

7.6 Charts

• Donut chart: Available balance vs spent
• Bar chart: Budget vs Actual per variable expense category
• Pie chart: Expense breakdown by category
• Library: Recharts or similar React-compatible charting library

8. UI / Design

8.1 Color Scheme

Pastel color palette inspired by the reference screenshots:

• Soft blues, pinks, yellows, greens, lavenders
• Light backgrounds with subtle section dividers
• shadcn/ui components with custom pastel theme tokens

8.2 Layout

• Left sidebar or top nav for navigation (Dashboard, Categories, Settings)
• Main content area with the dashboard sections stacked vertically
• Responsive but desktop-first (primary use case)

8.3 Future: Customization

• Architecture should support theming (CSS variables / Tailwind config)
• Not implemented in MVP, but color tokens should be centralized for easy swapping later

9. API Endpoints (MVP)

Auth

Method	Path	Description
POST	/api/auth/register	Local registration
POST	/api/auth/login	Local login
POST	/api/auth/logout	Logout
GET	/api/auth/oidc	Initiate OIDC flow
GET	/api/auth/oidc/callback	OIDC callback
GET	/api/auth/me	Get current user

Categories

Method	Path	Description
GET	/api/categories	List user categories
POST	/api/categories	Create category
PUT	/api/categories/:id	Update category
DELETE	/api/categories/:id	Delete category

Budgets

Method	Path	Description
GET	/api/budgets	List user budgets
POST	/api/budgets	Create budget
GET	/api/budgets/:id	Get budget with items + totals
PUT	/api/budgets/:id	Update budget
DELETE	/api/budgets/:id	Delete budget
POST	/api/budgets/:id/copy-from/:srcId	Copy items from another budget

Budget Items

Method	Path	Description
POST	/api/budgets/:id/items	Create budget item
PUT	/api/budgets/:id/items/:itemId	Update budget item
DELETE	/api/budgets/:id/items/:itemId	Delete budget item

User Settings

Method	Path	Description
GET	/api/settings	Get user settings
PUT	/api/settings	Update user settings

10. Deployment

compose.yml

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/simplefinancedash?sslmode=disable
      - OIDC_ISSUER=https://auth.example.com
      - OIDC_CLIENT_ID=simplefinancedash
      - OIDC_CLIENT_SECRET=secret
      - SESSION_SECRET=change-me
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=simplefinancedash
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d simplefinancedash"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

Dockerfile

Multi-stage build:

1. Node stage: build React SPA
2. Go stage: embed SPA, compile binary
3. Final stage: minimal image (distroless or alpine) with single binary

11. Testing

Backend (Go)

• Unit tests for business logic and handlers
• Integration tests against a test PostgreSQL instance (testcontainers)
• API endpoint tests with httptest

Frontend (React)

• Component tests with Vitest + React Testing Library
• Page-level integration tests

E2E

• Playwright for critical user flows (login, create budget, edit items, view dashboard)

12. Non-Goals (MVP)

These are explicitly out of scope for v1 but should be kept in mind architecturally:

• CSV / bank import
• Recurring / automated transactions
• Shared / household budgets
• Custom themes / color picker
• GraphQL API
• PDF / CSV export
• Weekly / yearly views
• Mobile app

13. Future Considerations

• Customization engine: User-defined colors, layout preferences, category icons
• Sharing: Invite users to a shared budget (household mode)
• Automations: Recurring transactions, auto-carryover between months
• Summaries: Monthly/yearly reports with trends
• GraphQL: For flexible dashboard queries and aggregations
• Import/Export: CSV import from banks, PDF/CSV export of reports