# 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

## 🟡 MEDIUM

### 🟡 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:** Partial — Esc closes modals ✅, Cmd+K opens command palette ✅, arrow key tracker navigation ❌

**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 Notes:**
- ✅ `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 effort: 1-2 hours

---

### 🔵 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

---

### 🔵 Missing Bill Grouping and Reorganization API
**Added:** 2026-05-08 by Neo

**Description:**
No way to reorder bills, drag-and-drop, or group by custom criteria.

**Implementation Notes:**
- `sort_order` column to bills table (default NULL, ordered first by sort_order then due_day)
- `PUT /api/bills/reorder` endpoint accepting `{bill_id: new_index}`
- `PUT /api/bills/:id/archived` to soft-archive
- Estimated effort: 6 hours

---

## 💭 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