agent-skills

Expense Tracker

A multi-user expense & income tracker with a clean ASP.NET Core 10 backend and a React + Vite + shadcn/ui frontend. Designed for personal finance tracking with THB currency, Thai-friendly UI, system + custom categories, transaction CRUD, dashboard with charts, and CSV export.

📘 Full plan & architecture → docs/PLAN.md

📐 Project standards → .github/copilot-instructions.md

---

✨ Features

• Multi-user with email + password login
• Refresh-token JWT in HttpOnly + SameSite=Strict cookies (15-min access token in memory, 7-day rotated refresh token)
• Transactions with amount (decimal precision), date, category, note, type (income/expense)
• Categories — seeded system categories (read-only) + per-user custom categories
• Dashboard — current-month KPIs, 6-month trend line chart, top-10 by-category bar chart
• CSV export (Phase 2) — transactions and monthly summary, with filters
• RFC 7807 error responses; ProblemDetails middleware
• CSV injection guard (cells starting with =, +, -, @ are prefixed with ')
• E2E tests via Playwright CLI (CI) + Playwright-MCP (browser-driven dev/QA)

---

🧰 Tech Stack

Layer	Tech
Backend	.NET 10 (latest), ASP.NET Core, EF Core 10, Npgsql, FluentValidation, Serilog, BCrypt, CsvHelper
Frontend	React 19, Vite, TypeScript, shadcn/ui, Tailwind CSS, Recharts, React Query, React Hook Form + Zod, axios
Database	PostgreSQL 16 (Docker Compose locally; Testcontainers in CI)
Testing	xUnit + FluentAssertions (BE), Vitest + RTL + MSW (FE), Playwright (E2E)

---

📋 Prerequisites

Tool	Version	Notes
.NET SDK	10.0.x (latest feature band)	rollForward: latestFeature in backend/global.json — installs the newest 10.0.x automatically
Node.js	22 LTS (≥ 22.0.0, < 23)	frontend/.nvmrc and frontend/.node-version pin this. nvm use, fnm use, nvs, or asdf auto-switch on cd frontend/
Docker	Engine 24+ with Compose v2	Required for the local Postgres
Git	latest	—

💡 The frontend declares "engines": { "node": ">=22.0.0 <23" } in package.json — a Node 23+ install will fail npm ci.

Windows + WSL2 networking note

If your host is Windows 11 with WSL2 (and Postgres is running inside WSL2 via Docker or systemd), localhost:5432 from a Windows process will not reach WSL2's Postgres by default. WSL2's eth0 IP is NAT'd and unreachable from Windows user-mode processes.

The API and the integration tests in tests/ExpenseTracker.IntegrationTests/ already work end-to-end (the test host spins up Postgres via Testcontainers, which routes through the same Windows loopback as the API). But for a manual dotnet run of the API on Windows, you need a portproxy:

# Run PowerShell as Administrator
make db-wsl-ip          # prints the current WSL IP
make db-portproxy       # forwards localhost:5432 -> WSL:5432
make db-portproxy-remove

Under the hood: netsh interface portproxy add v4tov4 listenport=5432 listenaddress=0.0.0.0 connectport=5432 connectaddress=<WSL_IP>. See scripts/db-portproxy.ps1 for the script.

On macOS, Linux, or when the API runs inside WSL2, this is unnecessary — localhost:5432 works directly.

---

🚀 Quickstart

# 1. Clone the repository
git clone <repo-url> ExpenseTracker
cd ExpenseTracker

# 2. Start Postgres (detached, with healthcheck)
make db-up

# 3. One-time: populate per-developer user-secrets (Jwt:SecretKey + connection string).
#    Secrets are stored OUTSIDE the repo, never in tracked files.
make dev-secrets

# 4. Backend: install tools, apply migrations, run
cd backend
dotnet tool restore
dotnet ef database update --project src/ExpenseTracker.Infrastructure --startup-project src/ExpenseTracker.Api
dotnet run --project src/ExpenseTracker.Api
# → API at http://localhost:5000  ·  Swagger at http://localhost:5000/swagger

# 5. Frontend: install deps, run dev server (in a new terminal)
cd ../frontend
nvm use             # auto-switches to Node 22 LTS
npm ci
npm run dev
# → App at http://localhost:5173

Then open http://localhost:5173, register an account, and start logging transactions.

---

🧪 Verification

Run the full suite locally before opening a PR:

# Backend
cd backend
dotnet format --verify-no-changes
dotnet build -c Release
dotnet test

# Frontend
cd ../frontend
npm run lint
npm run typecheck
npm test
npm run build