budget-app/PRD.md

Budget App — Product Requirements Document

Overview

A self-hosted web app for managing semi-monthly paychecks and bill assignments. The user gets paid twice a month and wants to plan which bills come out of each paycheck, track actuals, and see monthly/annual summaries.

Tech Stack

Layer	Choice	Reason
Frontend	React (Vite)	Component-based UI, fast dev server
Backend	Node.js + Express	REST API
Database	PostgreSQL	Docker-hosted, safe for concurrent LAN access
Hosting	Docker Compose	Self-hosted on LAN, single docker compose up

Architecture

Docker Compose
├── app (Node/Express + serves React build)
└── db  (PostgreSQL)

The Express server both serves the React frontend (static build) and exposes a /api REST layer. In development, Vite dev server proxies API calls to Express.

---

Configuration

• Pay dates: Configurable. Default: 1st and 15th of each month.
• Pay amount: Configurable gross and net per paycheck (can differ between the two).
• No authentication — single-user app.

---

Core Concepts

Paycheck

A paycheck represents one pay period (e.g. "March 1" or "March 15"). Each paycheck has:

• Pay date
• Gross amount
• Net (take-home) amount
• List of assigned bills/expenses
• Remaining balance = net − sum of assigned amounts

Bill

A recurring monthly charge assigned to a specific paycheck each month. Fields:

• Name
• Amount
• Due date (day of month)
• Assigned paycheck (1st or 15th)
• Category (e.g. Housing, Utilities, Subscriptions, Insurance)
• Active/inactive flag

Bill frequency is monthly only in v1.

Variable Expense

A spending category (e.g. Groceries, Gas) with no preset budget. Actuals are logged against a paycheck. No budget target in v1.

Savings Goal

A named savings allocation assigned to a paycheck with a fixed monthly contribution amount.

One-Time Expense

A non-recurring expense manually assigned to a specific paycheck for a specific month.

Actual

A logged transaction recording what was actually spent. Linked to a bill or expense category and a paycheck period.

---

Views

1. Paycheck View (main view)

Two-column layout per month — one column per paycheck.

Each paycheck column shows:

• Pay date + label (e.g. "March 1")
• Gross / Net pay
• List of assigned bills with amounts and due dates
• Paid / unpaid toggle per bill
• Variable expense actuals (logged amounts)
• Savings goal allocations
• One-time expenses
• Remaining balance (net − all assigned amounts)

Navigation: month-by-month (prev/next).

2. Monthly Summary

Per-month aggregate view:

• Total income (both paychecks)
• Total planned bills
• Total actuals logged
• Surplus/deficit

3. Annual Overview

Year-at-a-glance:

• Monthly totals in a table/grid
• Annual income, planned spend, actual spend
• Running surplus/deficit

---

Data Model (PostgreSQL)

-- App configuration
config (key, value)

-- Bill definitions
bills (id, name, amount, due_day, assigned_paycheck, category, active, created_at)

-- Paycheck instances per period
paychecks (id, period_year, period_month, paycheck_number, pay_date, gross, net)

-- Bills assigned to a paycheck period (overrides allowed per period)
paycheck_bills (id, paycheck_id, bill_id, amount_override, paid, paid_at)

-- Savings goals
savings_goals (id, name, amount, assigned_paycheck, active)

-- One-time expenses
one_time_expenses (id, paycheck_id, name, amount, paid, paid_at)

-- Variable expense categories
expense_categories (id, name)

-- Actual spending log
actuals (id, paycheck_id, category_id, bill_id, amount, note, date, created_at)

---

Build Phases

Phase 1 — Skeleton

• Docker Compose setup (app + postgres)
• Express app with health check
• React app shell (Vite, routing)
• Database migrations (all tables)
• Basic config API (get/set pay dates, pay amounts)

Phase 2 — Bills & Paychecks

• Bills CRUD (API + UI)
• Paycheck generation (auto-create paycheck records for a month)
• Paycheck view (assign bills, show balance)

Phase 3 — Tracking

• Mark bills paid/unpaid
• Log variable expense actuals
• One-time expenses

Phase 4 — Summaries

• Monthly summary view
• Annual overview