# 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