# 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 while keeping all AI features fully offline.

The first version is optimized for fast daily entry and a dashboard-first review flow. It uses fixed starter categories, a simple local database, a fully offline local LLM for private AI features, 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.
  - Support merchant-name-based category suggestion: apply deterministic merchant rules first, then use the local LLM only for unknown merchants.
  - Treat AI categorization as assistive: known merchants may auto-fill a category, but unknown-merchant suggestions should be confirmed before save.
- 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 a fully offline local model.
  - Ask the model to return:
    - spending pattern summary
    - unusual categories or spikes
    - paycheck-to-spend timing observations
    - practical next-month suggestions
  - Use AI for merchant-category suggestion as well as monthly summaries, but keep the final saved category under user control for ambiguous merchants.
- 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 `Ollama` with a local Qwen-class instruct model for offline inference in v1.
  - Keep the app functional when the local model is unavailable by returning a clear fallback message instead of failing silently.
- 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`
  - `POST /categories/suggest` with merchant/shop name input for local category suggestion
  - 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 offline `Ollama` integration.
- [ ] Add merchant-name category suggestion using merchant rules first and local-model fallback second.
- [ ] Render AI insight output in the dashboard with fallback behavior for sparse months.
- [ ] Add tests for validation, aggregates, persistence, local-model fallback behavior, and category suggestion.
- [ ] 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.
  - App returns a clear fallback message when `Ollama` or the local model is unavailable.
- Category suggestion:
  - Known merchants resolve deterministically to the expected category.
  - Unknown merchants fall back to the local model and return a suggested category.
  - Ambiguous suggestions require user confirmation before save.
- 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.
- Privacy matters more than hosted-model quality for this app, so AI features should stay fully offline.
- A recent local Qwen instruct model running through `Ollama` is the default model family for v1.