Christian Hood
0a88bb3d12
- PRD.md: full product requirements for the budget app - CLAUDE.md: repo guidance including td task management workflow - AGENTS.md: session startup instructions - .gitignore: comprehensive ignore rules for Node/React/Docker/editor artifacts Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
# 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)
|
||
|
||
```sql
|
||
-- 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
|