# Entries Pivot — Changelog & Implementation Notes

## Purpose
This document lists the required codebase changes to pivot from **spendings** to **entries** (including income), plus new features (buckets, recurring entries) and UI adjustments. It is the primary reference for implementation and debugging during the transition.

---

## Global Rename (Spendings → Entries)
### Terminology
- `spending` → `entry`
- `spendings` → `entries`
- UI labels should use “Entry” and “Entries” (or “Transaction(s)” if explicitly needed in copy).
- New entry type: **Spending** or **Income**.

### Codebase Areas to Rename
- **DB tables/columns**: `spendings`, `spending_tags` → `entries`, `entry_tags`
- **API routes**: `/api/spendings` → `/api/entries`
- **Server services**: `lib/server/spendings.ts` → `entries.ts`
- **Client wrappers**: `lib/client/spendings.ts` → `entries.ts`
- **Hooks**: `hooks/use-spendings.ts` → `use-entries.ts`
- **Components**: `spendings-panel`, `new-spending-modal`, `spending-details-modal`
- **Legacy shims**: remove spendings re-export stubs (components/hooks/lib and /api/spendings proxies)
- **Types**: `Spending` → `Entry`
- **Tests**: all spendings tests → entries tests

### Migration Record
- See [docs/SPENDINGS_TO_ENTRIES_SCHEMA_MIGRATION_RECORD.md](docs/SPENDINGS_TO_ENTRIES_SCHEMA_MIGRATION_RECORD.md).

---

## Entries Schema (Planned)
### New Fields
- `entry_type` enum (`SPENDING`, `INCOME`) or equivalent flag
- Recurring fields (see below)

### Existing Fields Kept
- `amount_dollars`, `occurred_at`, `notes`, `receipt_id`, `created_by`, `group_id`, etc.

---

## Recurring Entries (New Domain)
### Requirements
- Toggle recurring on entry creation
- Frequency: daily, weekly, biweekly, monthly, quarterly, yearly
- End conditions: never, after X occurrences, by date
- `next_run_at` set on creation (if start date is today, set to today)
- `last_executed_at` default `NULL`
- **Reminder:** execution will require cron/scheduler later (not implemented now)

### Data Model (Suggested)
- `is_recurring` boolean
- `frequency` enum
- `interval_count` integer
- `end_condition` enum
- `end_count` integer nullable
- `end_date` date nullable
- `next_run_at` date nullable
- `last_executed_at` date nullable

---

## Buckets (New Domain)
### Requirements
- Buckets are like tags with a **budget limit**
- Each bucket:
  - name, description, icon (from predefined set)
  - editable and deletable via modal
  - has a budget limit
  - shows total spending based on associated tags
- **Totals logic:**
  - For each tag in the bucket, collect all entries with that tag
  - Remove duplicates (unique entry IDs), then sum amounts
  - Overlapping tags between buckets are allowed

### UI Requirements
- New dashboard view for buckets
- Visual indicators near/over budget
- Hamburger menu: edit, delete, view details, auto‑fill spendings search
- Drag handle icon for reordering

---

## Modal Close Buttons
- Replace all modal close buttons with **“x”** in top‑right corner
- Use **New Spending Modal** (soon **New Entry Modal**) as the reference

---

## Spendings Dashboard → Entries Dashboard
### Filtering
Add filtering modal with:
- Amount range
- Date range
- Necessity
- Tags
- Text in notes
- Tags filter mode: **match all** vs **match any**

### Naming Pivot
- Rename dashboard, labels, filters, and API payloads to “entries”

---

## New Entry Modal (formerly New Spending Modal)
### Tagging & Navigation
- Fix tags not being added
- Allow dropdown navigation via typing
- Maintain highlighted index across list shrink/grow

### Validation UX
- Keep amount or tags borders red until filled
- If submit with missing fields:
  - Show “Please fill out this field” on both
  - Focus amount first, tags second

### Date Navigation
- Add 4 buttons around date input:
  - `<<` (back 1 week), `<` (back 1 day), `>` (forward 1 day), `>>` (forward 1 week)
- Format: `[ << ][ < ][ today’s date ][ > ][ >> ]`

### Recurring Toggle
- Toggle button near header: refresh icon tooltip “Toggle Recurring Entry”
- Header changes: “New One‑Time Expense” → “New Recurring Expense”
- Show/hide frequency and end condition inputs

### Income vs Spending Toggle
- Toggle under header to switch entry type
- Default to spending
- Update header: “New [One‑Time/Recurring] Income entry”
- Add icon left of amount input:
  - Income: stocks going up
  - Spending: money going down

---

## API / Server / Client / Hooks
### API
- New `/api/entries` endpoints (CRUD)
- New `/api/buckets` endpoints (CRUD)
- New `/api/recurring-entries` endpoints (CRUD)

### Server
- `lib/server/entries.ts`, `buckets.ts`, `recurring-entries.ts`
- Enforce auth + group membership

### Client / Hooks
- `lib/client/entries.ts`, `use-entries.ts`
- `lib/client/buckets.ts`, `use-buckets.ts`
- `lib/client/recurring-entries.ts`, `use-recurring-entries.ts`

---

## Tests
- Rename spendings tests to entries
- Add tests for:
  - income entries
  - recurring entries (validation only; no cron execution)
  - buckets CRUD
  - buckets totals with overlapping tags
  - filtering modal behavior

---

## Non‑Regression Rules
- Entries list endpoints must **never** return receipt image bytes
- Auth checks remain server‑side only

---

_Last updated: 2026-02-09_