budget-app/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Agent Workflow Rules

• Commit after every task: When a task is complete, stage all changed files and create a git commit before marking the task done.
• Keep documentation current: Update CLAUDE.md with any new commands, architecture details, or setup steps introduced by your task. Update PRD.md only if scope/design decisions changed.
• Mark tasks in td: td start <id> when beginning, td close <id> when done.
• Only the orchestrator touches td: Sub-agents must never call td commands directly. Concurrent td writes from parallel agents corrupt the SQLite database. The orchestrator handles all td start/td close calls before and after delegating to sub-agents.

Task Management

This project uses td (a local CLI) for task tracking. At the start of each session:

td usage --new-session   # required at conversation start or after /clear
td usage -q              # quick check for subsequent reads

Optional session labeling:

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).

Development

Run production stack (Docker):

docker compose up

Run development stack with live reload (Docker):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

Frontend only (Vite dev server):

cd client && npm install && npm run dev

Backend only (nodemon):

cd server && npm install && npm run dev

Application Structure

The default route / renders the paycheck-centric main view (client/src/pages/PaycheckView.jsx). It shows the current month's two paychecks side-by-side with bills, paid status, one-time expenses, and remaining balance. Month navigation (prev/next) fetches data via GET /api/paychecks?year=&month=.

Theming: client/src/ThemeContext.jsx provides light/dark mode via CSS custom properties on [data-theme]. Preference persists in localStorage and defaults to prefers-color-scheme. All design tokens live in client/src/index.css.

Charts: Monthly Summary and Annual Overview use Recharts (SVG-based). Monthly Summary shows a spending breakdown donut and variable-by-category bar. Annual Overview shows income vs. spending, surplus/deficit trend, and stacked variable spending by category — all driven by the single GET /api/summary/annual?year= endpoint.

Bill amount locking: When a paycheck_bill is marked paid, amount_override is set to the bill's current amount, locking in the historical value. Unmarking clears the override.