94 lines
6.3 KiB
Markdown
94 lines
6.3 KiB
Markdown
# 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.
|