chore: untrack private docs (STRUCTURE, FUTURE, HISTORY, DEVELOPMENT_LOG)
This commit is contained in:
null
parent
34b0f75918
commit
d2acf44846
|
|
@ -1,3 +1,15 @@
|
||||||
|
# Private project/agent docs — never commit
|
||||||
|
DEVELOPMENT_LOG.md
|
||||||
|
PROJECT.md
|
||||||
|
STRUCTURE.md
|
||||||
|
FUTURE.md
|
||||||
|
HISTORY.md
|
||||||
|
BUILD_SUMMARY.md
|
||||||
|
SCRIPTS.md
|
||||||
|
project-requirements.md
|
||||||
|
.learnings/
|
||||||
|
|
||||||
|
# Dependencies
|
||||||
node_modules/
|
node_modules/
|
||||||
dist/
|
dist/
|
||||||
db/*.db
|
db/*.db
|
||||||
|
|
|
||||||
|
|
@ -1,175 +0,0 @@
|
||||||
# Bill Tracker - Development Log
|
|
||||||
|
|
||||||
**Purpose:** Track active development work across all agents. Bishop uses this to update Engineering_Reference_Manual.md.
|
|
||||||
|
|
||||||
**⚠️ Note for Agents:** When you complete your task, update this file with results, completion status, and any files modified. Ripley will then notify Bishop to review and decide on manual updates. You have `write` and `edit` access to this file.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### v0.26.1 — Dual-Column XLSX Parser Bug Fixes
|
|
||||||
**Status:** ✅ COMPLETED
|
|
||||||
**Date:** 2026-05-11
|
|
||||||
**Priority:** HIGH
|
|
||||||
|
|
||||||
| Agent | Status | Time | Notes |
|
|
||||||
|-------|--------|------|-------|
|
|
||||||
| Bishop | ✅ COMPLETED | 15m | Build verified, version bumped, test runtime validated |
|
|
||||||
| Ripley | ✅ COMPLETED | 10m | Bugfixes implemented and verified with real spreadsheet |
|
|
||||||
|
|
||||||
**Files modified:** `services/spreadsheetImportService.js`, `package.json`, `client/lib/version.js`
|
|
||||||
|
|
||||||
**Work Completed:**
|
|
||||||
- [x] **`detectAllHeaderSets()` rewritten** — Uses repeat-field detection instead of gap-based splitting. Second "Bill" or "Amount" column starts a new group. Requires ≥2 header fields per group (filters out "Left Over | Paid" rows).
|
|
||||||
- [x] **Column leakage fixed** — `allColumnsIndices` Set includes full range [startCol..endCol] for every header set, passed to `analyzeRow` and `collectNotesCells`. Prevents right-side bills from picking up left-side amounts.
|
|
||||||
- [x] **`header_set_index` added to output** — `analyzeRow` return object now includes `header_set_index` so frontend can distinguish left vs right bills.
|
|
||||||
- [x] **`isLikelySummaryRow()` added** — Catches Paycheck, Left Over, Enter how much, Starting/Ending Balance rows.
|
|
||||||
- [x] **`isLikelyTotalRow()` expanded** — Catches "Auto Total ------>" patterns.
|
|
||||||
- [x] **Leftover calc rows filtered** — null/blank bill name + negative amount, or dash-separator names like "--------->".
|
|
||||||
- [x] **`HEADER_PATTERNS.amount`** — Removed `paid` from alternation (was matching "Paid" text as a header).
|
|
||||||
- [x] **Empty cell filter** in `detectAllHeaderSets` — Skips cells with empty string values.
|
|
||||||
|
|
||||||
**Functional Test Results (verified by Ripley):**
|
|
||||||
|
|
||||||
January 2026 sheet from real spreadsheet:
|
|
||||||
- ✅ 15 left-side bills (due ~1st), 12 right-side bills (due ~15th)
|
|
||||||
- ✅ No null-name rows, no dash names, no negative amounts
|
|
||||||
- ✅ Amazon chase card correctly shows null amount (no column leakage)
|
|
||||||
- ✅ All amounts parse correctly
|
|
||||||
|
|
||||||
**Build & Runtime Verification:**
|
|
||||||
|
|
||||||
1. ✅ Build completed successfully:
|
|
||||||
```
|
|
||||||
Successfully built 97480952ed3e
|
|
||||||
Successfully tagged bill-tracker:local
|
|
||||||
```
|
|
||||||
|
|
||||||
2. ✅ Container started on http://localhost:3036
|
|
||||||
|
|
||||||
**Changes Applied:**
|
|
||||||
|
|
||||||
**Version bump:**
|
|
||||||
- `package.json`: `0.26.0` → `0.26.1`
|
|
||||||
- `client/lib/version.js`: `APP_VERSION = '0.26.1'`
|
|
||||||
- `client/lib/version.js`: RELEASE_NOTES version updated with v0.26.1 highlights
|
|
||||||
|
|
||||||
**Files Modified:**
|
|
||||||
- `services/spreadsheetImportService.js` - Dual-column parser bugfixes (already verified by Ripley)
|
|
||||||
- `package.json` - Version bumped to 0.26.1
|
|
||||||
- `client/lib/version.js` - APP_VERSION and RELEASE_NOTES updated
|
|
||||||
|
|
||||||
**Deliverables:**
|
|
||||||
- XLSX dual-column parser correctly detects multiple header sets using repeat-field detection
|
|
||||||
- XLSX dual-column parser prevents column leakage between left and right column groups
|
|
||||||
- API response includes `header_set_index` for frontend column distinction
|
|
||||||
- Summary rows (Paycheck, Left Over, Auto Total) correctly filtered
|
|
||||||
- Amount header pattern no longer false-matches "Paid" text
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### v0.24.6 — XLSX Dual-Column Parser Bug Fixes
|
|
||||||
**Status:** ✅ COMPLETED
|
|
||||||
**Date:** 2026-05-11
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
|
|
||||||
| Agent | Status | Time | Notes |
|
|
||||||
|-------|--------|------|-------|
|
|
||||||
| Neo | ✅ COMPLETED | 2m | Added filter for null-name + negative amount rows and dash separators |
|
|
||||||
| Bishop | ✅ COMPLETED | 2m | Build verified, parsed data cleaned |
|
|
||||||
|
|
||||||
**Files modified:** `services/spreadsheetImportService.js`
|
|
||||||
|
|
||||||
**Work Completed:**
|
|
||||||
- [x] **Bug 1 Fixed:** Added filter in `parseSheetRows` to skip rows where bill name is null/blank AND amount is negative (leftover calculation rows)
|
|
||||||
- [x] **Bug 1 Fixed:** Added filter to skip rows where bill name matches `/^-+>/` or `/^--+$/` (dash separators like "--------->")
|
|
||||||
- [x] **Bug 2 Verified:** `header_set_index` was already present in API output (no changes needed)
|
|
||||||
- [x] **Bug 3 Verified:** "kids lunches" has null amount because the spreadsheet cell is genuinely empty (correct behavior, not a bug)
|
|
||||||
- [x] Docker build passes, container starts, import preview shows 27 rows instead of 29 (removed 2 leftover calculation rows)
|
|
||||||
|
|
||||||
**Changes Applied:**
|
|
||||||
|
|
||||||
**Before (buggy behavior):**
|
|
||||||
- Row 23 (Excel row 24): Left side `[null, null, "-$3,429.47", ...]` parsed as bill with null name and negative amount
|
|
||||||
- Row 23 (Excel row 24): Right side `["--------->", null, "-$1,915.78", ...]` parsed as bill named "--------->" with negative amount
|
|
||||||
|
|
||||||
**After (fixed behavior):**
|
|
||||||
- Both rows skipped during parsing
|
|
||||||
- Total rows reduced from 29 to 27
|
|
||||||
- No null-name or negative-amount rows in parsed output
|
|
||||||
|
|
||||||
**Code Added (in `parseSheetRows` loop):**
|
|
||||||
```javascript
|
|
||||||
// Skip leftover calculation rows: null/blank bill name with negative amount, or dash separators
|
|
||||||
const getBillName = (field) => {
|
|
||||||
const idx = headerMap[field];
|
|
||||||
return idx !== undefined ? cells[idx] : undefined;
|
|
||||||
};
|
|
||||||
const get = (field) => {
|
|
||||||
const idx = headerMap[field];
|
|
||||||
return idx !== undefined ? cells[idx] : undefined;
|
|
||||||
};
|
|
||||||
const rawBillName = getBillName('bill_name') ?? cells[0];
|
|
||||||
const billName = rawBillName ? String(rawBillName).trim() || null : null;
|
|
||||||
const rawAmount = get('amount') ?? findFirstAmountCell(cells, new Set(Object.values(headerMap)));
|
|
||||||
const amount = rawAmount !== null ? parseAmount(rawAmount) : null;
|
|
||||||
|
|
||||||
// Check if bill name is a dash separator (--- or ---->)
|
|
||||||
const isDashSeparator = billName && (billName.match(/^-+>/) || billName.match(/^--+$/));
|
|
||||||
|
|
||||||
// Check if this is a leftover calculation row (null/blank bill name + negative amount)
|
|
||||||
// Skip if bill name is null AND amount is negative
|
|
||||||
const isLeftoverCalcRow = !billName && amount !== null && amount < 0;
|
|
||||||
|
|
||||||
if (isDashSeparator || isLeftoverCalcRow) continue;
|
|
||||||
```
|
|
||||||
|
|
||||||
**Test Results:**
|
|
||||||
|
|
||||||
**Header Detection:** ✅ PASSED
|
|
||||||
- Left set: startCol=0, endCol=4, defaultDueDay=1
|
|
||||||
- Right set: startCol=6, endCol=9, defaultDueDay=15
|
|
||||||
|
|
||||||
**Parsing:** ✅ PASSED
|
|
||||||
- 27 rows parsed (down from 29)
|
|
||||||
- No null-name + negative-amount rows
|
|
||||||
- No dash-separator rows
|
|
||||||
|
|
||||||
**API Output:** ✅ PASSED
|
|
||||||
- `header_set_index` present in all rows
|
|
||||||
- Correctly assigns 0 to left column bills, 1 to right column bills
|
|
||||||
|
|
||||||
**Files Modified:**
|
|
||||||
- `services/spreadsheetImportService.js` - Added row skip filter in `parseSheetRows`
|
|
||||||
|
|
||||||
**Deliverables:**
|
|
||||||
- XLSX dual-column parser correctly filters calculation leftover rows
|
|
||||||
- XLSX dual-column parser correctly filters dash separator rows
|
|
||||||
- `header_set_index` available in preview API response for frontend column distinction
|
|
||||||
- Kids lunches null amount correctly reflects genuine empty cell (not a parsing bug)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### v0.24.4 - Analytics Mobile Layout + Previous Month Payment Toggle
|
|
||||||
**Status:** ✅ COMPLETED
|
|
||||||
**Date:** 2026-05-11
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
|
|
||||||
| Agent | Status | Time | Notes |
|
|
||||||
|-------|--------|------|-------|
|
|
||||||
| Scarlett | ✅ COMPLETED | 12m | Mobile responsiveness fixes for AnalyticsPage |
|
|
||||||
| Neo | ✅ COMPLETED | 3m | Toggle-paid scoped to year/month on backend + frontend |
|
|
||||||
| Bishop | ✅ COMPLETED | 7m | Build verified, runtime tested, version bumped |
|
|
||||||
|
|
||||||
**Files modified:** `client/pages/AnalyticsPage.jsx`, `routes/bills.js`, `client/pages/TrackerPage.jsx`, `package.json`, `client/lib/version.js`
|
|
||||||
|
|
||||||
**Work Completed:**
|
|
||||||
- [x] AnalyticsPage: Heatmap table responsive (removed min-w-760px, narrower columns)
|
|
||||||
- [x] AnalyticsPage: Controls grid breakpoints (sm:grid-cols-2 → lg:grid-cols-6)
|
|
||||||
- [x] AnalyticsPage: Chart card grid (sm:grid-cols-1 → lg:grid-cols-2)
|
|
||||||
- [x] AnalyticsPage: Donut chart responsive SVG sizing
|
|
||||||
- [x] AnalyticsPage: Checkbox grid mobile layout
|
|
||||||
- [x] AnalyticsPage: Loading skeleton mobile height
|
|
||||||
- [x] Backend: toggle-paid accepts year/month params, scopes payment lookup to specific month
|
|
||||||
- [x] Backend: paid_date calculated from due_day when year/month provided but no explicit date
|
|
||||||
|
|
||||||
[... remaining content unchanged from original file ...]
|
|
||||||
330
FUTURE.md
330
FUTURE.md
|
|
@ -1,330 +0,0 @@
|
||||||
# Bill Tracker — Future Improvements
|
|
||||||
|
|
||||||
**This document tracks potential future enhancements for Bill Tracker.**
|
|
||||||
|
|
||||||
**Last Updated:** 2026-05-11
|
|
||||||
**Current Version:** v0.24.3
|
|
||||||
|
|
||||||
## 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 neds 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
|
|
||||||
|
|
||||||
### 🔴 No Confirmation Before Destructive Actions — CRITICAL
|
|
||||||
**Priority:** CRITICAL
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
Deleting a bill or payment is one click with no confirmation dialog and no undo. For a financial app, accidental data loss destroys user trust.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Bills and payments represent real financial commitments and history
|
|
||||||
- No "are you sure?" prompt before delete
|
|
||||||
- No undo mechanism, no soft delete, no recovery
|
|
||||||
- One misclick = gone forever — unacceptable for financial data
|
|
||||||
- This is a trust and data integrity issue, not a UX nicety
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add confirmation dialog to all delete actions (bills, payments, categories)
|
|
||||||
- Consider soft delete (`deleted_at` column) with a grace period before permanent removal
|
|
||||||
- Add undo toast after delete that allows restoration within a short window
|
|
||||||
- Files to modify: `BillModal.jsx`, `BillsTableInner.jsx`, `TrackerPage.jsx`, `CategoriesPage.jsx`
|
|
||||||
- Estimated effort: 3-4 hours
|
|
||||||
|
|
||||||
|
|
||||||
### 🟠 HIGH
|
|
||||||
|
|
||||||
### 🟠 No Search or Filter Across Bills — HIGH
|
|
||||||
**Priority:** HIGH
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
No way to find a bill by name, category, or amount. Users must scroll through the entire list to find anything. Every bill tracker on the market has instant search.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- With dozens of bills, scrolling is slow and error-prone
|
|
||||||
- No search bar on BillsPage, TrackerPage, or CalendarPage
|
|
||||||
- Can't filter by category, amount range, autopay status, or billing cycle
|
|
||||||
- Can't quickly find "where's that electric bill?" without visually scanning
|
|
||||||
- Table stakes for any list-based app
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add search input to BillsPage (filter by name, category, notes)
|
|
||||||
- Add filter chips/dropdowns for category, billing cycle, autopay, active/inactive
|
|
||||||
- Add search to TrackerPage (filter visible rows by bill name)
|
|
||||||
- Consider a global `Cmd+K` / `Ctrl+K` command palette for instant bill lookup
|
|
||||||
- Files to modify: `BillsPage.jsx`, `TrackerPage.jsx`, `client/api.js`
|
|
||||||
- Estimated effort: 6-8 hours
|
|
||||||
|
|
||||||
### 🟠 No Visible Overdue Indicators — HIGH
|
|
||||||
**Priority:** HIGH
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
Overdue bills aren't visually flagged on the tracker. An unpaid past-due bill looks the same as one not due yet. The `notify_overdue` setting exists but there's no visual distinction in the UI.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- The whole point of a bill tracker is to not miss payments
|
|
||||||
- Overdue bills should be impossible to overlook — red highlight, badge count, sticky alert
|
|
||||||
- Data model supports overdue notifications but tracker grid shows no overdue state
|
|
||||||
- Users scanning the tracker won't notice a missed bill buried in the list
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add overdue detection: if today > due date for current month and no payment logged, mark overdue
|
|
||||||
- Red/amber background on overdue tracker rows
|
|
||||||
- Overdue count badge in Sidebar next to Tracker nav link
|
|
||||||
- Optional: overdue summary banner at top of TrackerPage
|
|
||||||
- Files to modify: `TrackerPage.jsx`, `Sidebar.jsx`, `routes/tracker.js` (add overdue count to API response)
|
|
||||||
- Estimated effort: 4-6 hours
|
|
||||||
|
|
||||||
### 🟠 Filtered Export for Reports — HIGH
|
|
||||||
**Priority:** HIGH
|
|
||||||
**Added:** 2026-05-11 by Ripley (upgraded from LOW)
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
No way to export filtered data (e.g., "all bills in category X for last 6 months", "everything overdue in 2026"). Export dumps everything or nothing.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Exporting filtered reports is core functionality for a bill tracker, not a nice-to-have
|
|
||||||
- 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
|
|
||||||
- This is how people actually use financial data outside the app
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
|
|
||||||
### 🟡 MEDIUM
|
|
||||||
|
|
||||||
### 🟡 No Bill Template / Duplicate Bill — MEDIUM
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
Creating a new bill means filling 10+ fields every time. No way to duplicate an existing bill or use a template. If you have 3 utilities from the same provider, you're retyping everything.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Bill creation has many fields (name, category, due day, amount, autopay, website, account, 2FA, notes)
|
|
||||||
- Common pattern: similar bills from same provider or same category with slight variations
|
|
||||||
- "Duplicate bill" is table stakes in every bill tracker
|
|
||||||
- Reduces friction and errors during bill setup
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add "Duplicate" button/action on each bill row and in BillModal
|
|
||||||
- Pre-fill all fields from source bill, clear `name` and set "(Copy)" suffix
|
|
||||||
- Files to modify: `BillModal.jsx`, `BillsPage.jsx`, `routes/bills.js` (POST endpoint can accept `source_bill_id` param)
|
|
||||||
- Estimated effort: 3-4 hours
|
|
||||||
|
|
||||||
### 🟡 No Partial Payment Support — MEDIUM
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
The UI only supports logging a single payment per bill per month. The `payments` table schema supports multiple entries per bill, but the frontend doesn't surface this. Split payments (half now, half later) can't be tracked.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Many bills get paid in installments (medical, tuition, large utilities)
|
|
||||||
- Payment plan arrangements require tracking multiple payments against one bill
|
|
||||||
- The data model already supports it — it's purely a frontend gap
|
|
||||||
- Without this, users either over-record or under-record partial payments
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Show payment history per bill in tracker (expandable row or modal tab)
|
|
||||||
- Allow "Add partial payment" with amount + date, summing to bill total
|
|
||||||
- Display remaining balance on partially-paid bills
|
|
||||||
- Files to modify: `TrackerPage.jsx`, `routes/payments.js`, possibly `BillModal.jsx`
|
|
||||||
- Estimated effort: 6-8 hours
|
|
||||||
|
|
||||||
### 🟡 No Year-Over-Year Comparison in Analytics — MEDIUM
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
Analytics shows monthly trends within a single year but there's no "this month vs same month last year" view. Users can't evaluate whether spending is improving.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- The whole point of analytics is answering "am I doing better or worse?"
|
|
||||||
- Within-year trends are useful but don't show long-term improvement
|
|
||||||
- Comparing April 2026 to April 2025 is the natural question people ask
|
|
||||||
- Available in every competing app (YNAB, Monarch, etc.)
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add YoY comparison toggle or tab to AnalyticsPage
|
|
||||||
- Query: same month range across current and previous year, diff the totals
|
|
||||||
- Show percentage change and absolute change per category
|
|
||||||
- Files to modify: `AnalyticsPage.jsx`, `routes/analytics.js` (add YoY endpoint or params)
|
|
||||||
- Estimated effort: 6-8 hours
|
|
||||||
|
|
||||||
### 🟡 No Bulk Actions — MEDIUM
|
|
||||||
**Priority:** MEDIUM
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**Description:**
|
|
||||||
Every action is one-at-a-time. Can't select multiple bills and mark them paid, skip them for a month, or change their category.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- End-of-month reconciliation means marking many bills as paid in a row
|
|
||||||
- Category reorganization affects multiple bills at once
|
|
||||||
- Skipping seasonal bills for summer/winter requires individual clicks
|
|
||||||
- Bulk actions are standard in any list-based management UI
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- Add checkbox selection to BillsPage rows (with select-all toggle)
|
|
||||||
- Bulk action toolbar: Mark Paid, Skip This Month, Change Category, Delete
|
|
||||||
- Backend: batch endpoints or loop with progress indicator
|
|
||||||
- Files to modify: `BillsPage.jsx`, `BillsTableInner.jsx`, `routes/bills.js`, `routes/payments.js`
|
|
||||||
- Estimated effort: 8-10 hours
|
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
|
|
||||||
### 🔵 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." No standardized method options, no summary.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Useful for reconciling credit card statements vs bank statements
|
|
||||||
- Autopay vs manual tracking helps identify bills that should be switched to autopay
|
|
||||||
- Payment method breakdown is a common analytics view in financial apps
|
|
||||||
- Current `method` field is unvalidated free text — no consistency
|
|
||||||
|
|
||||||
**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` or `SummaryPage.jsx`, schema migration for method validation
|
|
||||||
- Estimated effort: 4-6 hours
|
|
||||||
|
|
||||||
### 🔵 No Keyboard Navigation or Shortcuts — LOW
|
|
||||||
**Priority:** LOW
|
|
||||||
**Added:** 2026-05-11 by Ripley
|
|
||||||
|
|
||||||
**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. Power users and accessibility need keyboard support.
|
|
||||||
|
|
||||||
**Rationale:**
|
|
||||||
- Keyboard accessibility is required for WCAG compliance
|
|
||||||
- Power users navigate faster with keyboard shortcuts
|
|
||||||
- Modal dismiss on `Esc` is expected behavior in any modern app
|
|
||||||
- Command palette (`Cmd+K`) pairs with the search feature (also missing)
|
|
||||||
|
|
||||||
**Implementation Notes:**
|
|
||||||
- `Esc` closes any open modal/dialog
|
|
||||||
- `Cmd+K` / `Ctrl+K` opens search/command palette
|
|
||||||
- Arrow keys navigate tracker rows when grid is focused
|
|
||||||
- Tab order follows logical flow, not DOM order
|
|
||||||
- Files to modify: `App.jsx`, `BillModal.jsx`, `TrackerPage.jsx`, all dialog components
|
|
||||||
- Estimated effort: 6-8 hours
|
|
||||||
|
|
||||||
### 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 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
|
|
||||||
1274
HISTORY.md
1274
HISTORY.md
File diff suppressed because it is too large
Load Diff
277
STRUCTURE.md
277
STRUCTURE.md
|
|
@ -1,277 +0,0 @@
|
||||||
# Bill Tracker Project Structure
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
Bill Tracking Website — Full-stack application with Node.js backend and React frontend.
|
|
||||||
|
|
||||||
## Directory Structure
|
|
||||||
```
|
|
||||||
bill-tracker/
|
|
||||||
├── client/ # React frontend (ALL UI CODE HERE)
|
|
||||||
│ ├── components/ # Reusable React components
|
|
||||||
│ │ ├── layout/ # Layout components (Sidebar, etc.)
|
|
||||||
│ │ └── ui/ # UI components (buttons, inputs, etc.)
|
|
||||||
│ ├── pages/ # Page components (one per route)
|
|
||||||
│ │ ├── TrackerPage.jsx
|
|
||||||
│ │ ├── BillsPage.jsx
|
|
||||||
│ │ ├── CategoriesPage.jsx
|
|
||||||
│ │ ├── CalendarPage.jsx
|
|
||||||
│ │ ├── SummaryPage.jsx
|
|
||||||
│ │ ├── AnalyticsPage.jsx
|
|
||||||
│ │ ├── ProfilePage.jsx
|
|
||||||
│ │ ├── SettingsPage.jsx
|
|
||||||
│ │ ├── DataPage.jsx
|
|
||||||
│ │ ├── AdminPage.jsx
|
|
||||||
│ │ ├── LoginPage.jsx
|
|
||||||
│ │ └── AboutPage.jsx
|
|
||||||
│ ├── hooks/ # Custom React hooks (useAuth, etc.)
|
|
||||||
│ ├── api.js # API client functions
|
|
||||||
│ ├── App.jsx # React Router configuration
|
|
||||||
│ ├── main.jsx # React entry point
|
|
||||||
│ └── index.html # HTML template
|
|
||||||
├── server.js # Express backend entry
|
|
||||||
├── routes/ # API route handlers
|
|
||||||
├── services/ # Business logic layer
|
|
||||||
├── middleware/ # Express middleware
|
|
||||||
├── db/ # Database schemas/migrations
|
|
||||||
├── workers/ # Background job workers
|
|
||||||
├── scripts/ # Utility scripts
|
|
||||||
├── docs/ # Documentation
|
|
||||||
├── dist/ # Build output (generated)
|
|
||||||
├── public/ # Static assets
|
|
||||||
├── Dockerfile # Container config
|
|
||||||
└── docker-compose.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
## Critical Notes for Agents
|
|
||||||
|
|
||||||
### Frontend Code Location
|
|
||||||
**ALL React components, pages, and UI code are in `client/` folder.**
|
|
||||||
- Pages: `client/pages/*.jsx`
|
|
||||||
- Components: `client/components/**/*.jsx`
|
|
||||||
- Hooks: `client/hooks/*.js`
|
|
||||||
- API client: `client/api.js`
|
|
||||||
- Router: `client/App.jsx`
|
|
||||||
|
|
||||||
### Backend Code Location
|
|
||||||
**ALL backend code is at root or in server folders:**
|
|
||||||
- Entry: `server.js`
|
|
||||||
- Routes: `routes/*.js`
|
|
||||||
- Services: `services/*.js`
|
|
||||||
- Middleware: `middleware/*.js`
|
|
||||||
- Database: `db/*.js`
|
|
||||||
|
|
||||||
## Agent Review Roles
|
|
||||||
|
|
||||||
| Agent | Role | Focus Area |
|
|
||||||
|-------|------|------------|
|
|
||||||
| Neo | Backend / System Architecture | server.js, routes/, services/, middleware/, workers/, db/, Docker, performance, scalability, security |
|
|
||||||
| Scarlett | UI/UX / Frontend | client/, public/, components, styling, accessibility, responsive design |
|
|
||||||
| Bishop | Analysis / Code Quality | overall architecture, patterns, maintainability, technical debt |
|
|
||||||
| Private_Hudson | Security / Compliance | auth, data protection, input validation, compliance |
|
|
||||||
|
|
||||||
### Cross-Cutting Concerns
|
|
||||||
All agents must be aware of:
|
|
||||||
- **Routing**: `client/App.jsx` defines all frontend routes
|
|
||||||
- **Auth**: `client/hooks/useAuth.jsx` and `services/authService.js`
|
|
||||||
- **API**: `client/api.js` mirrors `routes/` structure
|
|
||||||
- **Database**: `db/database.js` schema affects both frontend and backend
|
|
||||||
|
|
||||||
## Review Output
|
|
||||||
All findings appended to `REVIEW.md` per agent section.
|
|
||||||
|
|
||||||
# OpenClaw Agent Structure
|
|
||||||
|
|
||||||
## Prime
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* executive coordinator
|
|
||||||
* project strategist
|
|
||||||
* Discord command interface
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* **Overall Oversight:** Must maintain high-level awareness of all concurrent projects, ensuring every agent's output aligns with the goal set in `projects-requirements.md`.
|
|
||||||
* **Coordination & Directives:** Direct agent activity by issuing tasks that fit within the approved technology stack and operational guidelines.
|
|
||||||
* **Priority Setting:** Assign priorities while constantly cross-referencing potential conflicts with established system mandates (e.g., Security > Performance > Feature).
|
|
||||||
* **Escalation & Blockers:** Must be the first point of contact when any agent flags a requirement conflict or a technical blocker that contradicts the mandated best practices.
|
|
||||||
* **High-Level Strategy:** Must ensure that any strategy proposed is *future-proof*, *lightweight*, and avoids accumulating technical debt against the required state of the stack.
|
|
||||||
* **Communication:** Must communicate status, outcomes, and required actions to the human user, translating technical mandates into actionable project milestones.
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* project coordination and task routing.
|
|
||||||
* Authority to pause or redirect any agent whose proposed path violates the Universal Mandate or project requirements.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Riply
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* operations
|
|
||||||
* infrastructure
|
|
||||||
* runtime management
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* deployment oversight, adhering to stability and resilience standards (per `projects-requirements.md`).
|
|
||||||
* runtime monitoring, ensuring all services are low-latency and avoid unnecessary polling.
|
|
||||||
* infrastructure coordination, guaranteeing that all components use the approved stack (Next.js, React, etc.).
|
|
||||||
* operational alerts, prioritizing security and performance issues immediately.
|
|
||||||
* service stability, adhering to the "fail gracefully" principle.
|
|
||||||
* environment consistency, ensuring local/localhost parity across development.
|
|
||||||
* Discord operational reporting, following established communication protocols.
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* infrastructure operations, strictly governed by stability and security mandates.
|
|
||||||
* deployment workflows, must pass full security and performance audits before proceeding.
|
|
||||||
* runtime diagnostics, must use established, non-bloated tooling.
|
|
||||||
* operational communication, must be precise and action-oriented.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Neo
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* senior backend developer
|
|
||||||
* backend architecture lead
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* **Mandatory Adherence:** Must treat `projects-requirements.md` as the primary source of truth for all technology choices and operational philosophies.
|
|
||||||
* **Security First:** All data handling, authentication, and authorization logic must strictly follow OWASP best practices and the principle of least privilege. No assumption of trust.
|
|
||||||
* **Data Integrity:** Must ensure all database operations use transactions and validate inputs/outputs to prevent silent failures.
|
|
||||||
* **Business Logic Separation:** Must keep core business logic separate from the API routes to maintain clear separation of concerns.
|
|
||||||
* **API Consistency:** Must ensure all endpoints are well-documented, predictable, and enforce structured error handling.
|
|
||||||
* **Resilience:** Must design for restart-safe operation and predictable data flow, especially when handling configuration from environment variables.
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* ultimate authority over the integrity and security of the data layer and business logic flow.
|
|
||||||
* must block any integration or design that compromises data integrity or security posture.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Scarlett
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* frontend developer
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* **Mandatory Adherence:** Must treat `projects-requirements.md` as the primary source of truth for UI/UX.
|
|
||||||
* **Reactivity & Performance:** Must ensure all components feel instantly reactive, minimizing layout shifting, and never blocking the main thread or rendering loop.
|
|
||||||
* **UI/UX Authority:** Must enforce modern standards (2026 feel), rejecting outdated patterns.
|
|
||||||
* **Component Purity:** Must use shadcn/ui components consistently and build complex logic in modular, clean ways, avoiding deeply nested structures.
|
|
||||||
* **Responsiveness:** Must ensure flawless behavior across desktop and mobile (responsive design is non-negotiable).
|
|
||||||
* **Accessibility & States:** Must build in required accessibility compliance, explicit loading, and error states.
|
|
||||||
* **Integration:** Must strictly adhere to the backend API contract provided by Neo while maintaining clean client-side state management.
|
|
||||||
|
|
||||||
Technology Focus:
|
|
||||||
|
|
||||||
* **React with Vite** is the frontend framework (NOT Next.js — never suggest Next.js patterns).
|
|
||||||
* **Tailwind CSS** must be used predictably to maintain consistency.
|
|
||||||
* **shadcn/ui** is the foundational component library — always use shadcn/ui components for UI primitives (buttons, dialogs, inputs, selects, etc.). Do not build custom components when shadcn/ui provides one.
|
|
||||||
* **Sonner** is used for toast notifications.
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* UI architecture and frontend interaction flows.
|
|
||||||
* Must halt any feature development that compromises perceived performance or usability.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Bishop
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* code reviewer
|
|
||||||
* architecture validator
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* Must enforce adherence to `projects-requirements.md` standards across the entire lifecycle.
|
|
||||||
* **Architecture Validation:** Must review all designs to ensure they follow the modular, low-coupling approach defined in the requirements.
|
|
||||||
* **Code Quality Review:** Beyond syntax, must audit for architectural flaws, overengineering, and non-compliance with best practices (readability, maintainability).
|
|
||||||
* **Standard Enforcement:** Must enforce the use of approved components (shadcn/ui, Tailwind) and discourage workarounds or non-approved patterns.
|
|
||||||
* **Testing Validation:** Must verify that all proposed changes include adequate test coverage as per best practices.
|
|
||||||
* **Dependency Review:** Must audit all dependencies against vulnerability reports and stability metrics.
|
|
||||||
* **Implementation Consistency:** Must ensure the final code pattern matches the intended architecture outlined in the requirements.
|
|
||||||
* **Failure Detection:** Must actively search for anti-patterns that violate performance or complexity standards.
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* approve or reject code quality based *only* on adherence to established standards and the mandate in `projects-requirements.md`.
|
|
||||||
* require revisions that address specific violations of architecture, performance, or consistency.
|
|
||||||
* enforce project standards by citing specific sections of the requirements document.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Private Hudson
|
|
||||||
|
|
||||||
Role:
|
|
||||||
|
|
||||||
* security reviewer
|
|
||||||
* defensive operations specialist
|
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
* OWASP validation
|
|
||||||
* authentication security review
|
|
||||||
* authorization validation
|
|
||||||
* dependency vulnerability auditing
|
|
||||||
* secret exposure detection
|
|
||||||
* injection vulnerability analysis
|
|
||||||
* security hardening review
|
|
||||||
* infrastructure security analysis
|
|
||||||
* runtime security assessment
|
|
||||||
|
|
||||||
Authority:
|
|
||||||
|
|
||||||
* approve or reject security posture
|
|
||||||
* block insecure deployments
|
|
||||||
* require remediation before release
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Universal Mandate
|
|
||||||
|
|
||||||
**All agents are governed by the guidelines set in `projects-requirements.md`.** Every decision, design choice, and implementation detail must strictly adhere to the philosophy, technology stack, standards, and policies defined in that file. Failure to adhere constitutes a deviation from operational standards and must be flagged for review.
|
|
||||||
|
|
||||||
**Mandatory Adherence Checklist:**
|
|
||||||
1. **Always** refer to `projects-requirements.md` for the definitive ruleset.
|
|
||||||
2. Never implement functionality that contradicts the approved Tech Stack (Vite, React, React Router, Tailwind CSS, shadcn/ui, Sonner, SQLite via better-sqlite3, Express).
|
|
||||||
3. Treat security and performance checks (per `projects-requirements.md`) as *primary* considerations, not secondary checks.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technology Stack
|
|
||||||
|
|
||||||
Bill Tracker actual stack:
|
|
||||||
|
|
||||||
* **Vite** (build tool, NOT Next.js)
|
|
||||||
* **React** (SPA, client-side routing via React Router)
|
|
||||||
* **Tailwind CSS** (utility-first styling)
|
|
||||||
* **shadcn/ui** (component primitives — buttons, dialogs, inputs, etc.)
|
|
||||||
* **Sonner** (toast notifications)
|
|
||||||
* **TanStack Query** (server state management)
|
|
||||||
* **better-sqlite3** (database)
|
|
||||||
* **Express** (backend)
|
|
||||||
|
|
||||||
⚠️ **This project does NOT use Next.js.** Do not suggest Next.js patterns (App Router, server components, etc.).
|
|
||||||
|
|
||||||
Development target:
|
|
||||||
|
|
||||||
* localhost based development
|
|
||||||
* modular architecture
|
|
||||||
* maintainable systems
|
|
||||||
* production ready implementation
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
*Generated by Prime for multi-agent review*
|
|
||||||
Loading…
Reference in New Issue