FinTrack — Architecture & Flows

Start the App

Full startup — scheduler + FastAPI (recommended)

python main.py

API at :8000 · start React separately

Fast restart — skip initial data load

python main.py --skip-initial

API only — no scheduler (dev)

uvicorn api.main:app --reload --port 8000

Frontend

React dev server

cd frontend && npm run dev

Runs at http://localhost:5173

Production build

cd frontend && npm run build

Start the Agent (before bed)

Run in VS Code terminal — stops at 6:20am

.\start-agent.ps1

Loops through BACKLOG.md overnight. Commits locally to agent/feat-* branches — nothing pushed until you review.

When You Wake Up

Review what the agent built

start agent-log.html

Merge completed branches into main

/merge-agent-branches

Run in Claude Code. Merges all agent/feat-* branches that have an agent-log.md into main, then deletes them.

Push to GitHub when happy

git push origin main

Add a Feature

Edit BACKLOG.md — add under ## Queue

- [ ] **slug** — description of what to build

Agent picks from the top of Queue each session. Priority order matters.

Stop the Agent

Kill the running session

Ctrl + C

Safe to stop mid-session — the agent commits what it has before each pause.