BillTracker/FUTURE.md

# Bill Tracker — Future Improvements

**This document tracks potential future enhancements for Bill Tracker.**

**Last Updated:** 2026-05-30  
**Current Version:** v0.34.2

## How to Use This Document

This file is a living document. Agents should:

1. Read this file before proposing changes
2. Add new recommendations with priority levels
3. Never add completed items — move those to HISTORY.md instead
4. Reference this file when dispatching improvement tasks
5. Only Ripley can remove items from this list. Notify Ripley if something needs to be removed.

### Priority Format

All items must include the priority emoji in their heading, matching the section they belong to:

| Priority     | Emoji | Heading Format                |
| ------------ | ----- | ----------------------------- |
| CRITICAL     | 🔴    | `### 🔴 Title — CRITICAL`     |
| HIGH         | 🟠    | `### 🟠 Title — HIGH`         |
| MEDIUM       | 🟡    | `### 🟡 Title — MEDIUM`       |
| LOW          | 🔵    | `### 🔵 Title — LOW`          |
| NICE TO HAVE | 💭    | `### 💭 Title — NICE TO HAVE` |

Items are grouped under their priority section heading (`## 🔴 CRITICAL`, `## 🟠 HIGH`, etc.) and sorted most-impactful-first within each tier.

## Pending Recommendations

## 🟠 HIGH

### 🟡 Projected Cash Flow — MEDIUM

**Priority:** MEDIUM  
**Added:** 2026-05-16 by Ripley (from _null's prioritized roadmap)

**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

**Priority:** MEDIUM  
**Added:** 2026-05-16 by Ripley (from _null's prioritized roadmap)

**Status:** Partial — infrastructure built (auto_mark_paid column, confirm/dismiss APIs, UI for suggestions), but no proactive suggestion scheduler generating payments on due date.

**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 Notes:**

- ✅ `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
- Estimated effort remaining: 2-3 hours

---

### 🟡 Calendar Agenda Mode — MEDIUM

**Priority:** MEDIUM  
**Added:** 2026-05-16 by Ripley (from _null's prioritized roadmap)

**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

**Priority:** MEDIUM (upgraded from LOW)  
**Added:** 2026-05-11 by Ripley (from _null's prioritized roadmap)

**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

### 🔵 Payment Method Tracking and Summary — LOW

**Priority:** LOW  
**Added:** 2026-05-11 by Ripley

**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

**Added:** 2026-05-11 by Ripley

**Status:** Done — Esc closes modals ✅, Cmd+K opens command palette ✅, arrow key tracker navigation ✅

**Description:**
Skip link, command palette, and tracker-row keyboard navigation are all implemented.

**Implementation Notes:**

- ✅ `Esc` closes any open modal/dialog (via Radix Dialog default)
- ✅ `Cmd+K` / `Ctrl+K` opens command palette (`CommandPalette.tsx`)
- ✅ Arrow keys / `j`/`k` navigate tracker rows, `Enter` edits, `p` toggles paid (`TrackerRow.tsx` `handleRowKeyDown`, focusable `[data-tracker-row]`)
- Nice-to-have: a `?`-triggered shortcut legend for discoverability

---

### 🔵 Add comprehensive unit and integration tests

**Added:** 2026-05-08 by Scarlett

**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

### 💭 Add consistent form state management pattern

**Priority:** MEH  
**Added:** 2026-05-08 by Scarlett

**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