monthlytracker/openspec/changes/monthly-expense-tracker-v1/proposal.md

Why

The project currently has a product plan but no runnable application, spec artifacts, or implementation scaffold. Formalizing the first version now creates a clear contract for building a local-first expense tracker with reliable monthly summaries and AI-generated guidance.

What Changes

• Add a local-first web app for tracking expenses and biweekly paychecks without authentication.
• Add dashboard capabilities for month-to-date totals, category breakdowns, cash flow, and spending comparisons.
• Add manual AI insight generation for a selected month using structured aggregates and transaction samples.
• Add local persistence, validation, and API routes for expenses, paychecks, dashboard data, and insight generation.

Capabilities

New Capabilities

• expense-tracking: Record, list, and delete categorized expenses for a given date.
• paycheck-tracking: Record, list, and delete paycheck entries based on actual pay dates.
• monthly-dashboard: View month-specific spending, income, and derived financial summaries.
• monthly-insights: Generate read-only AI insights from monthly financial activity.

Modified Capabilities

• None.

Impact

• Affected code: new Next.js application, server routes, UI views, Prisma schema, and AI integration service.
• APIs: POST/GET/DELETE routes for expenses and paychecks, GET /dashboard, and POST /insights/generate.
• Dependencies: Next.js, Prisma, SQLite, and OpenAI SDK.
• Systems: local machine timezone handling for month boundaries and persisted local database storage.