commit 0a88bb3d12b81e5f822270a69e87bec489ef0b1e Author: Christian Hood Date: Thu Mar 19 18:56:20 2026 -0400 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..31c0d31 --- /dev/null +++ b/.gitignore @@ -0,0 +1,43 @@ +# td / sidecar +.todos/ +.sidecar/ +.sidecar-agent +.sidecar-task +.sidecar-pr +.sidecar-start.sh +.sidecar-base +.td-root + +# Dependencies +node_modules/ + +# Build output +dist/ +build/ +.vite/ + +# Environment +.env +.env.local +.env.*.local + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# OS +.DS_Store +Thumbs.db + +# Editor +.vscode/ +.idea/ +*.swp +*.swo + +# Coverage +coverage/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e8fd43b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +## MANDATORY: Use td for Task Management + +Run td usage --new-session at conversation start (or after /clear). This tells you what to work on next. + +Sessions are automatic (based on terminal/agent context). Optional: +- td session "name" to label the current session +- td session --new to force a new session in the same context + +Use td usage -q after first read. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dbf068e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Task Management + +This project uses `td` (a local CLI) for task tracking. At the start of each session: + +```bash +td usage --new-session # required at conversation start or after /clear +td usage -q # quick check for subsequent reads +``` + +Optional session labeling: +```bash +td session "name" # label the current session +td session --new # force a new session in the same terminal context +``` + +Task state is stored in `.todos/issues.db` (SQLite). diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..86c8653 --- /dev/null +++ b/PRD.md @@ -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