monthlytracker/AGENT_HANDOFF.md

Monthy Tracker Agent Handoff

Use this file as the starting point for any new agent. It summarizes the repo state, the important files, and the non-obvious behavior so you can continue without re-discovering basics.

What this app is

• Single-user, local-first monthly expense tracker.
• Stack: Next.js App Router, Prisma, SQLite, Ollama for offline AI.
• Main views: dashboard, add expense, income/paychecks.
• Goal: track expenses and paychecks, then generate private monthly summaries and recommendations.

Current state

• Dashboard data is loaded from /dashboard?month=YYYY-MM.
• Monthly insight generation lives in src/lib/insights.ts.
• The app is currently working with the local dev DB at file:./prisma/dev.db.
• Seed data exists for February 2026 and March 2026.
• The frontend shows the current month by default, so if data looks missing, check the active month selector first.

Important files

• src/components/home-dashboard.tsx - dashboard UI, fetches dashboard and Ollama status.
• src/lib/dashboard.ts - aggregates totals, breakdowns, recent expenses, and comparisons.
• src/lib/insights.ts - builds the model prompt, calls Ollama, stores fallback/model insights.
• src/app/dashboard/route.ts - dashboard API route.
• src/app/backup/database/route.ts - SQLite backup endpoint.
• src/lib/date.ts - month/date helpers; month filtering uses local date strings.
• prisma/schema.prisma - data model source of truth.
• prisma/seed.ts - local seed script.
• README.md - setup and runtime notes.
• openspec/changes/monthly-expense-tracker-v1/ - design/spec/task source for the product.

Key behavior to know

• Dashboard aggregates all records, then filters them to the selected month in memory.
• getCurrentMonthKey() uses local machine time.
• generateMonthlyInsight() in src/lib/insights.ts:
  • builds a structured prompt from dashboard totals, category breakdown, recent expenses, and chart points
  • expects strict JSON with summary and recommendations
  • falls back when activity is sparse or Ollama is unavailable
  • stores the final result in MonthlyInsight
• The fallback message is intentionally safe and short when data is too sparse.

Known gotchas

• If dashboard values appear missing, confirm the selected month matches the seeded data.
• If Docker backup fails, check DATABASE_URL; the backup route reads the SQLite path from the env var.
• Prisma migration ordering matters because migration folders are applied lexicographically.
• In Docker Compose on Linux, extra_hosts: host-gateway is needed for host Ollama access.

Current enhancement target

• The next useful improvement is making the generated monthly summary more helpful and more structured.
• Best place to change it: src/lib/insights.ts.
• Likely changes:
  • strengthen the prompt with clearer sections or required observations
  • improve the fallback logic for sparse months
  • optionally store more structured fields in MonthlyInsight
  • update the dashboard card rendering in src/components/home-dashboard.tsx if the output shape changes

Useful commands

npm run dev
npx prisma migrate deploy
npx prisma db seed
npm test

If you need to verify the dashboard API directly:

curl "http://localhost:3000/dashboard?month=2026-03"

Recommended next step for another agent

1. Read src/lib/insights.ts, src/lib/dashboard.ts, and prisma/schema.prisma.
2. Decide whether to improve the insight prompt, the stored data shape, or the dashboard rendering.
3. Make the change, then verify with the dashboard API and a generated insight.