BillTracker/roadmap.md

# Bill Tracker Roadmap

This document tracks the planned features and enhancements for Bill Tracker, organized by priority and implementation status.

## 🟡 MEDIUM Priority Items

### 🟡 Projected Cash Flow — MEDIUM
**Status:** Not implemented

**Description:**
Show users what's coming: "You'll have $X left before the 15th", "Upcoming bills before next paycheck", and a "Safe-to-spend" estimate based on starting amount, unpaid bills, and scheduled income. Fits naturally with the existing 1st/15th bucket model.

**Scope:**
- "Remaining after bills" projection per bucket (1st half / 15th half)
- "Upcoming bills before next paycheck" list
- "Safe-to-spend" estimate based on starting balance minus unpaid bills
- Scheduled income support (payday amounts)

**Rationale:**
- The 1st/15th bucket model is already built — cash flow projection is the natural next step
- Most valuable feature for day-to-day money management
- Turns a bill tracker into a financial planning tool

**Implementation Notes:**
- Requires user to enter starting balance and payday amounts (new settings fields)
- Calculate: starting amount - unpaid bills due before next payday = safe-to-spend
- Files to modify: `TrackerPage.jsx`, `routes/tracker.js`, `user_settings` table (new fields)
- Estimated effort: 8-10 hours

---

### 🟡 Recurring Payment Rules — MEDIUM
**Status:** Partially implemented

**Description:**
Auto-mark certain bills as paid on due date if `autodraft_status = assumed_paid`. Or create suggested payments awaiting confirmation. Good for autopay-heavy users.

**Scope:**
- Bills with autopay/autodraft get a "suggested payment" on their due date
- User confirms or dismisses the suggestion
- Auto-mark option: bills can be set to automatically mark as paid on due date

**Implementation Status:**
- ✅ `auto_mark_paid` column + bill edit checkbox
- ✅ `applyAutopaySuggestions()` in trackerService handles auto-mark + suggestion generation
- ✅ Confirm (`POST /api/payments/autopay-suggestions/:billId/confirm`) and dismiss (`POST /.../dismiss`) endpoints
- ✅ Suggestion UI in TrackerPage with badge + confirm/dismiss buttons
- ❌ No proactive suggestion engine — only runs when tracker loads
- ❌ No scheduled task/cron to evaluate bills and create suggestions on due date

**Remaining Work:**
- Implement scheduled task/cron to evaluate bills and create suggestions on due date
- Estimated effort remaining: 2-3 hours

---

### 🟡 Calendar Agenda Mode — MEDIUM
**Status:** Not implemented

**Description:**
Replace the month-grid calendar with an agenda view: Today / This Week / Next 14 Days. Group bills by "needs action," "autopay," "already paid." More useful when actually paying bills.

**Rationale:**
- Month grids are pretty but not actionable
- Agenda mode answers "what do I need to do right now?"
- Groups by status makes it immediately clear what needs attention

**Implementation Notes:**
- New view toggle on CalendarPage: Grid vs Agenda
- Agenda shows: Overdue → Today → This Week → Next 14 Days
- Each group sorted by due date, with action status badges
- Files to modify: `CalendarPage.jsx`, `routes/calendar.js`
- Estimated effort: 6-8 hours

---

### 🟡 Filtered Exports — MEDIUM
**Status:** Not implemented

**Description:**
Export only utilities, debts, overdue, date range, tax-relevant categories. Currently exports everything with no filtering.

**Rationale:**
- Users need "all Q1 utility bills" or "overdue payments this year" for reconciliation and tax prep
- `/api/export/user-excel` exports everything — no query params for date range, category, or status

**Implementation Notes:**
- Add query params to export endpoints: `category_id`, `start`, `end`, `status` (paid/unpaid/overdue)
- Files to modify: `routes/export.js`, `client/pages/DataPage.jsx`
- Estimated effort: 6 hours

---

## 🔵 LOW Priority Items

### 🔵 Payment Method Tracking and Summary — LOW
**Status:** Not implemented

**Description:**
The `payments` table has a `method` column (free-text) but no way to see "how much did I pay via autopay vs manual vs credit card this month."

**Implementation Notes:**
- Standardize payment methods: enum or controlled list (autopay, bank_transfer, credit_card, check, cash, other)
- Add payment method breakdown to analytics or summary page
- Files to modify: `routes/payments.js`, `AnalyticsPage.jsx`, schema migration
- Estimated effort: 4-6 hours

---

### 🔵 No Keyboard Navigation or Shortcuts — LOW
**Status:** Partially implemented

**Description:**
Only a skip link exists for keyboard accessibility. No `Cmd+K` to find a bill, no `Esc` to close modals, no arrow keys to navigate the tracker grid.

**Implementation Status:**
- ✅ `Esc` closes any open modal/dialog (via Radix Dialog default)
- ✅ `Cmd+K` / `Ctrl+K` opens command palette (`CommandPalette.jsx`)
- ❌ Arrow keys navigate tracker rows when grid is focused

**Remaining Work:**
- Implement arrow key navigation for tracker rows
- Estimated effort: 1-2 hours

---

### 🔵 Add comprehensive unit and integration tests
**Status:** Not implemented

**Description:**
Currently no unit tests exist for components or hooks. The only testing is functional tests in `test-functional.js`.

**Implementation Notes:**
- Set up Jest + React Testing Library (or vitest)
- Test key components: BillModal, TrackerPage row, BillsTableInner
- Test hooks: useAuth, custom form hooks
- Test utility functions in `client/lib/utils.js`
- Estimated effort: 8-12 hours for baseline coverage

---

## 💭 NICE TO HAVE Items

### 💭 Add consistent form state management pattern
**Status:** Not implemented

**Description:**
Form state management is inconsistent across components. Some use `useState` for each field, others use form libraries.

**Implementation Notes:**
- Consider react-hook-form for complex forms
- Create reusable form field components (InputField, SelectField, etc.)
- Standardize validation approach
- Estimated effort: 4-6 hours