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