fiddy/docs/bucket-usage-audit.md

Bucket Usage Audit (2026-02-11)

What exists

• Buckets table: buckets in packages/db/migrations/005_buckets.sql
• Entries table: entries (pivoted from spendings) in packages/db/migrations/004_entries_pivot.sql and base definition in packages/db/migrations/001_init.sql
• Tags storage: tags, entry_tags, bucket_tags in packages/db/migrations/002_tags.sql and packages/db/migrations/005_buckets.sql
• Recurrence fields: entries.is_recurring plus recurrence columns in packages/db/migrations/004_entries_pivot.sql
• Necessity enum (entries): spending_necessity in packages/db/migrations/001_init.sql
• Existing usage calc: totalSpent based on tag overlap in apps/web/lib/server/buckets.ts
• Bucket API routes: apps/web/app/api/buckets/route.ts and apps/web/app/api/buckets/[id]/route.ts

Missing before this change

• Bucket necessity (no column or API fields)
• Bucket windowDays (no column or API fields)
• Bucket usage rules for recurrence/necessity/date window
• Entry necessity value BOTH (enum was aligned to BOTH)

Endpoints impacted

• Buckets list/create/update in apps/web/app/api/buckets/route.ts
• Buckets update/delete in apps/web/app/api/buckets/[id]/route.ts
• Entries and recurring entries endpoints for necessity validation

Notes

• Tag matching uses bucket_tags and entry_tags join tables.
• Recurrence flag is entries.is_recurring.
• occurred_at is date in the DB (not timestamp).
• windowDays default set to 30 (min 1, max 365).
• Necessity uses spending_necessity enum with BOTH.