60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```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).
|
|
|
|
## Development
|
|
|
|
**Run production stack (Docker):**
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
**Run development stack with live reload (Docker):**
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
|
|
```
|
|
|
|
**Frontend only (Vite dev server):**
|
|
```bash
|
|
cd client && npm install && npm run dev
|
|
```
|
|
|
|
**Backend only (nodemon):**
|
|
```bash
|
|
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](https://recharts.org) (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.
|