monthlytracker/plan.md

Monthly Expense Tracker With AI Insights

Summary

Build a single-user, local-first web app for manually recording daily expenses and biweekly paychecks, then generating month-to-date and end-of-month spending insights with next-month guidance.

The first version is optimized for fast daily entry and a dashboard-first review flow. It uses fixed starter categories, a simple local database, and an in-app AI summary rather than email or exports.

Implementation Changes

• App shape:
  • Build a web app with 3 primary views: Dashboard, Add Expense, and Income/Paychecks.
  • Keep it single-user and local-first with no authentication in v1.
• Core data model:
  • Expense: id, date, title, amount, category, createdAt.
  • Paycheck: id, payDate, amount, createdAt.
  • MonthlyInsight: id, month, year, generatedAt, summary, recommendations, inputSnapshot.
• Categories:
  • Ship with fixed starter categories such as Rent, Food, Transport, Bills, Shopping, Health, Entertainment, Misc.
  • Store category as a controlled value so monthly summaries can group reliably.
• Dashboard behavior:
  • Show current month totals for expenses, category breakdown, paycheck total, and net cash flow.
  • Include month-to-date charts and simple comparisons like highest category, largest single expense, average daily spend, and spend vs paycheck coverage.
  • Provide a Generate Insights action that works any time during the month, not only at month-end.
• AI insight generation:
  • Build a summarization pipeline that prepares structured monthly aggregates plus recent transaction samples, then sends that context to the AI model.
  • Ask the model to return:
    • spending pattern summary
    • unusual categories or spikes
    • paycheck-to-spend timing observations
    • practical next-month suggestions
  • Keep AI read-only in v1: it does not edit data or auto-categorize entries.
• Storage and architecture:
  • Use a simple embedded database for local-first persistence, preferably SQLite.
  • Implement the app with Next.js for the web UI and server routes.
  • Use Prisma for the data layer and migrations.
  • Keep the AI integration behind a small service boundary so the model/provider can be swapped later without changing UI code.
  • Use OpenAI for insight generation in v1.
• Public interfaces / APIs:
  • POST /expenses, GET /expenses, DELETE /expenses/:id
  • POST /paychecks, GET /paychecks, DELETE /paychecks/:id
  • GET /dashboard?month=YYYY-MM
  • POST /insights/generate?month=YYYY-MM
  • Insight response should include structured fields for totals and a rendered narrative summary for the dashboard.

Implementation Checklist

• Scaffold the Next.js app and set up base project config.
• Add Prisma with a SQLite database and define Expense, Paycheck, and MonthlyInsight models.
• Build shared validation and month/date helpers using local machine time.
• Implement expense CRUD routes and forms.
• Implement paycheck CRUD routes and forms.
• Build dashboard aggregation logic for totals, categories, cash flow, and comparisons.
• Add the insight generation service boundary and OpenAI integration.
• Render AI insight output in the dashboard with fallback behavior for sparse months.
• Add tests for validation, aggregates, persistence, and insight generation.
• Verify all month-boundary behavior using local timezone dates.

Test Plan

• Expense entry:
  • Create valid expense with title, amount, date, and category.
  • Reject missing or invalid amount/date/category.
• Paycheck tracking:
  • Record multiple biweekly paychecks in one month and across month boundaries.
  • Verify dashboard cash-flow totals use actual paycheck dates, not monthly averaging.
• Dashboard calculations:
  • Category totals, monthly totals, average daily spend, and net cash flow are correct.
  • Current-month partial data still renders meaningful month-to-date views.
• Insight generation:
  • AI request uses aggregated monthly inputs plus transaction samples.
  • Manual generation works for current month and prior months with existing data.
  • Empty or near-empty months return a safe fallback message instead of low-quality advice.
• Persistence:
  • Data remains available after app restart.
  • Deleting an expense or paycheck updates dashboard and future insight results correctly.

Assumptions And Defaults

• First version is for your own use only, with no login or multi-user support.
• Expense entry is fully manual; receipt scanning and bank sync are out of scope.
• AI insights appear only inside the dashboard.
• The app supports month-to-date previews as well as end-of-month review.
• Fixed starter categories are sufficient for v1; custom categories can be added later.
• Income is modeled as discrete biweekly paychecks because that materially affects next-month guidance and intra-month cash-flow interpretation.
• Month and paycheck boundaries use the local machine timezone.