Add project docs and initial configuration
- 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>
This commit is contained in:
154
PRD.md
Normal file
154
PRD.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user