# 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

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

If you need to verify the dashboard API directly:

```bash
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.