EPIC-05: Budget Management

[steilerDev]

Epic: Budget Management

Epic ID: EPIC-05
Priority: Must Have
Sprint Suggestion: Sprint 3

Description

Implement the comprehensive budget management system covering four sub-domains: category-based budgeting, vendor/contractor tracking with payments, budget sources (creditors/financing), and subsidy programs. This is a critical feature for homeowners who need visibility into where money is being spent, what financing is available, and how subsidies reduce costs. Budget linkage to work items and household items is bidirectional: work items and household items reference budget entities, and budget views aggregate from those entities.

Requirements Coverage

• Section 2.2: Budget Management (complete section)
  • Category-Based Budgeting
    • Pre-defined categories (Materials, Labor, Permits, Design, etc.)
    • Planned vs actual cost tracking per category
    • Budget variance alerts
  • Vendor/Contractor Tracking
    • Vendor database (name, contact info, specialty)
    • Payment history per vendor
    • Invoice tracking
    • Payment status (Pending, Paid, Overdue)
    • Outstanding balance calculations
  • Budget Sources (Creditors)
    • Multiple financing sources (bank loans, credit lines, savings, etc.)
    • Total amount per source
    • Used amount tracking
    • Available amount calculation
    • Interest rates and terms
    • Payment schedules to creditors
    • Notes per source
  • Subsidy Programs
    • Program database (name, description, eligibility)
    • Reduction type (percentage or fixed amount)
    • Reduction value
    • Application status tracking (Eligible, Applied, Approved, Received)
    • Application deadline tracking
    • Applicable categories
    • Apply to work items or household items
    • Automatic cost reduction calculations
    • Documenting and tracking of subsidy requirements
• Section 2.1: Work Items - Budget properties
  • Assigned budget amount
  • Actual cost tracking
  • Confidence calculation for estimating work item cost
  • Link to budget categories
  • Link to vendors/contractors
  • Associated subsidies
• Section 4: User Stories - Budget
  • Track budget by category
  • Track multiple financing sources
  • Apply subsidy programs to work items to see reduced cost
  • Track payments to vendors (paid vs outstanding)
  • See planned vs actual costs for budget overrun identification
  • Link invoices and receipts from Paperless-ngx (document linking in EPIC-08)

Dependencies

• EPIC-01: Authentication & User Management (access control)
• EPIC-02: Application Shell & Infrastructure (database and app shell)
• EPIC-03: Work Items Core CRUD (work items need to exist to link budgets)

Goals

• Budget category management (CRUD for categories, pre-defined defaults)
• Planned vs actual cost tracking per category with variance alerts
• Vendor/contractor database with full CRUD
• Payment tracking per vendor (create, status management, history)
• Invoice tracking with payment status workflow (Pending -> Paid / Overdue)
• Outstanding balance calculations per vendor
• Budget source (creditor) management with financing details
• Available amount calculations per source
• Subsidy program management with application status workflow
• Automatic cost reduction calculations when subsidies are applied
• Work item budget properties (assigned budget, actual cost, confidence, category/vendor/subsidy links)
• Budget dashboard showing overall financial health