# 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:
  ```js
  // 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

```markdown
### [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`.

---