BillTracker/FUTURE.md

Bill Tracker — Future Improvements

This document tracks potential future enhancements for Bill Tracker.

Last Updated: 2026-05-10
Current Version: v0.21.1

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

Add React Query (TanStack Query) for server state management

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

Description: Currently using manual useState/useEffect patterns with custom api wrapper for data fetching. This leads to duplicated loading/error handling, stale data issues, and no request caching.

Rationale: Developer experience and performance. React Query provides:

• Automatic request caching and stale-while-revalidate
• Background refetching
• Optimistic updates
• Request deduplication
• Built-in loading/error states

Implementation Notes:

• Replace manual API calls in pages with useQuery, useMutation
• Add query keys for cache invalidation
• Implement global query client with React Query DevTools
• Gradual migration: start with TrackerPage, then BillsPage, then AnalyticsPage
• Files likely to be modified: client/pages/*.jsx, add client/hooks/useQueryClient.js
• Estimated effort: 4-6 hours for full migration

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

Performance: N+1 Query Patterns in Tracker and Analytics

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

Description: Looping over bills and querying payments/state individually causes N+1 queries.

Rationale:

• tracker.js line 27-37: iterates over bills, runs mbsStmt.get() per bill
• analytics.js uses bills.map() and builds maps with per-bill lookups
• With 50 bills, this creates 100+ extra queries per request

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/routes/tracker.js, /analytics.js
• Estimated effort: 3 hours
• Use batch queries instead:

  // Fetch all monthly states for bills in one query
  const states = db.prepare(`
    SELECT * FROM monthly_bill_state
    WHERE bill_id IN (${billIds.join(',')}) AND year=? AND month=?
  `).all(billIds, year, month);
  

Security: Session Token Not Rotated on Auth Events

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

Description: Session tokens are not rotated on password change or logout events.

Rationale:

• admin.js deletes sessions on password change, but this is inconsistent
• /api/profile/change-password does not invalidate other sessions
• Logout only removes current session, doesn't invalidate others
• Session tokens are static — no rotation mechanism

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/services/authService.js
• Estimated effort: 4 hours
• Add:
  • session_version or token_seed column in users table
  • Increment seed on password change, logout all
  • Validate seed in getSessionUser()
  • Logout invalidates only current session (more usable)

Skip First-Login User Creation When ENV Seeds Users

Priority: MEDIUM
Added: 2026-05-09 by _null

Description: When INIT_ADMIN_USER/INIT_ADMIN_PASS (and optionally INIT_REGULAR_USER/INIT_REGULAR_PASS) are set via environment variables, the app still forces the first-login user creation flow. This is redundant — the admin user already exists from the seed, so presenting a "create your first user" form on login is confusing and unnecessary.

Implementation Notes:

• When INIT_ADMIN_USER is set, the app should skip the first-login user creation screen
• Admin should go directly to the main app after login
• The first_login flag on seeded users should be 0 (not forced to change password or create account)
• If no env vars are set, keep the current first-run flow unchanged
• Files likely to be modified: setup/firstRun.js, server.js seed logic, possibly frontend login flow

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.

---