BillTracker/FUTURE.md

Bill Tracker — Future Improvements

This document tracks potential future enhancements for Bill Tracker.

Last Updated: 2026-05-10
Current Version: v0.22.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.

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

🔴 CRITICAL

🟡 MEDIUM

Architecture: Business Logic Mixed with Route Handlers

Priority: MEDIUM
Added: 2026-05-08 by Neo

Description: Many routes contain business logic that should be extracted to service layers.

Rationale:

• bills.js contains parseDueDay(), parseInterestRate() — validation logic
• tracker.js contains date/range calculations that are reused across routes
• admin.js has complex OIDC config building mixed with routing
• analytics.js has complex date-building logic (buildMonths, monthKey, etc.)

Implementation Notes:

• Files to modify: Multiple route files + new service files in /services/
• Estimated effort: 8 hours
• Proposed structure:

  /services/billsService.js
  /services/trackerService.js
  /services/analyticsService.js
  /services/authService.js (existing)
  /services/oidcService.js (existing)
  /services/cleanupService.js (existing)
  

• Route handlers should call services, not contain business logic

Skip First-Login User Creation When ENV Seeds Users ✅ COMPLETED (v0.22.3)

Moved to HISTORY.md

No Rollback Capability for Failed Migrations

Priority: MEDIUM
Status: PENDING
Added: 2026-05-09 by Neo

Description: No way to rollback or recover from failed migrations without manual database repairs.

Rationale:

• If a migration fails, no automatic recovery
• Admin must manually fix database state
• No rollback scripts to revert breaking changes
• Risk: extended downtime on production

Implementation Notes:

• Design migrations with rollback functions
• Store rollback SQL alongside migration
• Implement ROLLBACK_LAST_MIGRATION functionality
• Document manual recovery procedures

Limited Error Handling and Logging for Migrations

Priority: MEDIUM
Status: PENDING
Added: 2026-05-09 by Neo

Description: Migration failures don't produce clear error messages or logs, making debugging difficult.

Rationale:

• Migration errors are silent or unclear
• No logging of which migration failed or why
• No way to diagnose schema inconsistencies
• Risk: slow debugging on production issues

Implementation Notes:

• Add detailed logging: [migration] Applying v0.20.0: Add user_groups table
• Include timing: [migration] v0.20.0 completed in 234ms
• Log precondition checks: [migration] Checking: table_exists('users')
• Error log with context: [migration-error] v0.20.0 failed: UNIQUE constraint failed on users.username

---

🔵 LOW

Add comprehensive unit and integration tests

Priority: LOW
Added: 2026-05-08 by Scarlett

Description: Currently no unit tests exist for components or hooks. The only testing appears to be functional tests in test-functional.js. Component-level testing is missing.

Rationale: Code quality and maintainability. Unit tests catch regressions and document component behavior. Bill Tracker has complex business logic (bill calculations, monthly state, analytics) that should be tested.

Implementation Notes:

• Set up Jest + React Testing Library
• Test key components: BillModal, TrackerPage row, BillsTableInner
• Test hooks: useAuth, custom form hooks
• Test utility functions in client/lib/utils.js
• Consider vitest for faster test execution
• Add CI integration for test execution
• Files likely to be modified: Add client/test/ directory, add jest.config.cjs
• Estimated effort: 8-12 hours for baseline coverage

Features: Missing Export for User-Specific Reports

Priority: LOW
Added: 2026-05-08 by Neo

Description: No built-in way to export filtered data (e.g., "all bills in category X for last 6 months").

Rationale:

• /api/analytics/summary exists but returns JSON only
• Users cannot generate Excel/PDF reports
• No programmatic way to get export links for specific filters
• /api/export/user-excel exports everything, not filtered views

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/routes/export.js
• Estimated effort: 6 hours
• Add endpoints:
  • GET /api/export/user-excel?category_id=1&start=2026-01&end=2026-06
  • GET /api/export/user-json?filter=bills&status=missed
  • Add report title/description to export metadata

Features: Missing Bill Grouping and Reorganization API

Priority: LOW
Added: 2026-05-08 by Neo

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

Rationale:

• bills table has due_day ordering but no manual sort order
• Frontend likely orders by due_day only
• Users cannot create bill groups or categories for bills
• No way to mark bills as "hidden" or "archived" without deactivating

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/db/schema.sql, /routes/bills.js
• Estimated effort: 6 hours
• Add:
  • 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-dearchive (sets archived flag)

---

💭 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. Validation patterns vary.

Rationale: Consistency and maintainability. A consistent pattern makes it easier to add new forms and reduce bugs.

Implementation Notes:

• Consider react-hook-form for complex forms
• Create reusable form field components (InputField, SelectField, etc.)
• Standardize validation approach
• Files likely to be modified: client/components/*.jsx
• Estimated effort: 4-6 hours for migration

---

Template for New Recommendations

### [Feature Name]
**Priority:** CRITICAL / HIGH / MEDIUM / LOW / MEH  
**Added:** YYYY-MM-DD by [Agent]

**Description:**
Brief description of the improvement.

**Rationale:**
Why this matters.

**Implementation Notes:**
- Technical approach
- Files likely to be modified
- Estimated effort

**Depends On:**
Any prerequisites or blocking issues.

Completed Items

✅ Security: Rate Limiting on /api/about-admin — MEDIUM

Completed: 2026-05-09 (v0.19.0) Fix: adminActionLimiter (30 req/15min) applied to /api/about-admin route.

✅ Security: Markdown Sanitization in AboutPage — MEDIUM

Completed: 2026-05-09 (v0.19.0) Fix: rehype-sanitize added to AboutPage.jsx ReactMarkdown component.

✅ Security: aboutAdmin() in API Client — LOW

Completed: 2026-05-09 (v0.19.0) Fix: aboutAdmin endpoint function added to client/api.js.

---