Expense Tracker

Personal and shared expense tracking with AI-assisted entry, split resolution, balances, budgets, and charts.

Requirements

• Node.js 18+
• MongoDB (local or Atlas)
• OpenAI API key (for AI parse & insights)

Setup

npm install
cp .env.example .env
# Edit .env: MONGODB_URI, OPENAI_API_KEY
npm run dev

Open http://localhost:3000 — you will be asked to log in.

Accounts

Users are stored in MongoDB (hashed passwords). On first visit:

1. Open Register → create account (name, email, password)
2. Login on return visits

Set AUTH_SECRET or NEXTAUTH_SECRET in .env for session cookies.

Sessions last 7 days (httpOnly cookie + Redux Persist for client auth state).

Each user only sees their own expenses and budgets.

Scripts

Command	Description
npm run dev	Development server
npm run build	Production build
npm run start	Run production build
npm run type-check	TypeScript check
npm run test	Unit tests (split + ledger)
npm run lint	ESLint
npm run db:flush -- --confirm	Delete all users, expenses, budgets (dev)
npm run db:flush -- --confirm --keep-users	Clear expenses & budgets only

Features

• Add expense — manual form or natural language (GPT-4o-mini) with preview before save
• 14+ categories — travel, food, rent, meds, etc. (src/lib/categories.ts)
• Splits — equal or custom; deterministic resolver ensures totals match
• Balances — who owes whom (computed, not stored)
• Budgets — monthly limits with 80% / 100% alerts (/budgets)
• Charts — pie, bar, line, area (/charts)
• Insights — AI summary from real stats (dashboard)
• Search & export — filter list, download CSV
• Edit / delete expenses
• Settings — your display name (cookie + localStorage)

API

Route	Methods
/api/expenses	GET, POST
/api/expenses/[id]	GET, PATCH, DELETE
/api/expenses/export	GET (CSV)
/api/parse	POST
/api/balances	GET
/api/budgets	GET, POST, DELETE
/api/charts	GET
/api/insights	GET
/api/health	GET
/api/settings	POST

Architecture

See docs/copilot-master-prompt.md, AGENTS.md, and docs/TODO.md for roadmap and remaining work.

Health check

curl http://localhost:3000/api/health