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

### 🟠 Cents Migration Stage 2 — Schema Flip to Integer Cents — HIGH
**Priority:** HIGH
**Added:** 2026-06-10 by Claude (cents migration stage 1)

**Description:**
Stage 1 is shipped: `utils/money.js` exists and all server-side money summation/
rounding is cent-exact. Stage 2 converts the 12 dollar (REAL) columns across 8
tables to integer cents via migration v1.03 and updates all ~288 query sites.

**Scope:**
- Apply v1.03 migration + rollback + schema.sql changes per `docs/cents-migration-plan.md`
- Convert reads/writes file-by-file in the documented order, on a branch
- Handle the four hazards: userDbImportService unit detection, CSV/spreadsheet
  import inserts, test fixtures (×100), CSV export formatting

**Rationale:**
- Eliminates float dollars at rest before the data grows further
- Unifies units with SimpleFIN transactions/accounts (already cents)
- The full plan, migration SQL, column inventory, and verification checklist are
  in `docs/cents-migration-plan.md` — this item is execution only

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

---


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