Skip to content
Trilogy Care Logo TC Docs

spec

Feature Specification: Funding Stream Balance in Package Sidebar

Feature Code: FRB (Funding Remaining Balance) Epic: TP-2501 (Budget Reloaded) Initiative: TP-1869 (Budgets and Services) Created: 2025-12-09 Status: Draft

Overview

Display current active funding stream balances prominently in the package sidebar, making available funding visible to care coordinators across all package management tabs without requiring navigation to the Service Plan view. This feature addresses the BUR initiative’s goal of improving “Human-Readable Funding Context” by surfacing critical funding information at the package level.

Core Business Need: Care coordinators need quick visibility into remaining funding for each stream (e.g., “ON $15,302.45”) to make informed decisions about service selection, supplier sourcing, and package modifications without context-switching to detailed budget views.

Problem Statement

Current State

  • Funding stream balances are only visible within the Service Plan tab’s detailed budget view
  • Coordinators must navigate away from Overview, Care Circle, Needs, or other tabs to see funding status
  • No global funding visibility across package management workflows
  • Limited context about available funding during service planning and supplier selection
  • Funding information is discovered late in workflow rather than informing early decisions

Pain Points

  1. Fragmented Workflows: Coordinators context-switch between tabs to answer simple questions like “How much ON funding is available?”
  2. Information Silos: Funding context (quantities, streams, availability) is not consistently visible across all package views
  3. Decision Friction: Service, supplier, and coordination decisions lack funding context until budget is explicitly opened
  4. Missed Opportunities: Coordinators don’t see funding constraints early enough to optimize service selection
  5. Cognitive Load: Must mentally track funding across multiple tabs and remember details

User Stories & Scenarios

User Story 1: Quick Funding Check During Service Planning

As a Care Coordinator (Romy, Jill, Patt) I want to see available funding for each stream in the package sidebar So that I can immediately assess funding constraints while planning services without switching to the Service Plan tab

Acceptance Criteria:

  • Funding stream balances display in package sidebar with colored badges (e.g., “ON $15,302.45”)
  • Display shows current active budget plan’s funding only
  • Balances are visible on every package tab (Overview, Care Circle, Needs, Risks, Service Plan, Notes, Bills, Statements, Claim History, Transactions, Contributions)
  • Data matches the Service Plan view’s funding information
  • Format is consistent with existing package metadata displays

Happy Path Scenario:

  1. Coordinator opens any package (e.g., Jane Recipient - SAH 3)
  2. Sidebar displays “Recipient Information” section with contact details
  3. Below recipient info, “Remaining balance by funding stream” section shows:
    • ON: $15,302.45 (with ON badge styling)
    • CM: $5,050.50 (with CM badge styling)
  4. Coordinator considers: “We have good ON funding but limited CM. Let’s minimize CM services.”
  5. Switches to Care Circle tab to adjust coordination ratio
  6. Funding balances remain visible in sidebar for reference

Alternative Scenario: Single Funding Stream

  • Package with only ON funding shows single badge: “ON $25,000.00”
  • Section still displays, avoiding jarring appearance changes

Alternative Scenario: No Funding

  • Package without active budget plan shows no funding section
  • Sidebar does not display “Remaining balance” heading (section is hidden)

User Story 2: Monitor Funding Changes After Budget Updates

As a Care Coordinator I want to see funding balances update in the sidebar after modifying a budget So that I can verify funding allocations immediately without page refresh

Acceptance Criteria:

  • Funding balances reflect current active budget plan state
  • Updates appear without page reload when navigating between tabs
  • Balances match Service Plan view at all times
  • If multiple budget plans exist, only current active plan’s data shows

Happy Path Scenario:

  1. Coordinator views package Overview with ON: $15,302.45 visible
  2. Navigates to Service Plan tab, modifies services
  3. Saves changes (budget is updated)
  4. Navigates back to Overview tab
  5. Sidebar now shows ON: $14,800.25 (updated)
  6. Coordinator confirms budget changes took effect

User Story 3: Empty State When No Budget Plan Exists

As a Care Coordinator I want to see clear indication when a package has no active funding So that I understand if budget setup is required before service planning

Acceptance Criteria:

  • When package has no budget plan, funding section is hidden entirely (not shown with “none” message)
  • Sidebar displays other package metadata normally
  • When budget is created, funding section appears automatically on next view
  • No error messages or loading states needed

Happy Path Scenario:

  1. New package created but no budget plan assigned yet
  2. Coordinator opens package Overview
  3. Sidebar shows Recipient Information, but no “Remaining balance” section
  4. Coordinator understands: “Need to create budget plan first”
  5. Later, after budget plan is created and activated, funding appears on next page load/tab switch

Functional Requirements

FR1: Display Funding Streams in Sidebar

  • Requirement: Sidebar displays a “This Quarter’s Funding” section below recipient information with funding stream balances
  • Details:
    • Section label: “This Quarter’s Funding” (indicates current quarter without explicit quarter date)
    • Each funding stream displays as a colored badge with format: “[StreamCode] $[Amount]” (e.g., “ON $25,000”, “CM $5,050”)
    • Badges use configured color from funding stream configuration (inherited from FundingStreamBadge.vue)
    • Amount currency formatted to 2 decimal places (e.g., “$25,000.00” or “$5,050.50”)
    • Layout: Two-column horizontal grid (2 badges per row), wraps to responsive layout on narrow screens
    • All available funding streams displayed (no maximum limit)
    • Tooltip content (on badge hover): Full funding stream name, quarter range, and additional context
    • When no budget plan exists, display centered empty state: “No Funding Streams” with subtle styling
  • Success Criterion: Section title clear, badges display code + amount only, full details accessible via tooltip, responsive 2-column layout

FR2: Data Source - Current Active Budget Plan

  • Requirement: Funding balances sourced from the current active (only) budget plan
  • Details:
    • “Active” means: using Service Plan logic to determine current quarter (see Quarter Determination below)
    • Only the active budget plan’s funding streams display (not multiple plans)
    • Display all funding streams from the active plan’s current quarter (including zero balances)
    • Available balance = total approved funding minus spent amounts
    • If no active budget plan exists, hide entire section and display empty state (FR1)
    • Funding section displays on Service Plan tab even though detailed budget view also shows funding (intentional redundancy for context awareness)
  • Success Criterion: Data matches Service Plan view’s funding display for same quarter

FR2a: Quarter Determination

  • Requirement: Determine which budget plan quarter to display using Service Plan logic
  • Details:
    • Use the same quarter selection logic as Service Plan controller:
      1. If explicit ?quarter=X parameter in URL, use that quarter
      2. Otherwise, use Quarter::getCurrent() (quarter where today’s date falls between start_date and end_date)
      3. If current quarter not selectable for this plan, use package commencement date’s quarter
      4. If still no match, use budget plan’s commencement quarter (fallback)
    • This ensures sidebar funding matches exactly what coordinator sees in Service Plan tab
    • Selectable quarters range from max(budget plan commencement, package commencement) through 2 quarters in future
  • Success Criterion: Sidebar quarter always matches Service Plan display without user action needed

FR3: Global Availability Across Package Tabs

  • Requirement: Funding section visible and functional on all package view tabs
  • Details:
    • Displays on: Overview, Care Circle, Needs, Risks, Service Plan, Notes, Bills, Statements, Claim History, Transactions, Contributions tabs
    • Data persists as user navigates between tabs (no loss of visibility)
    • Sidebar layout remains consistent across all tabs
  • Success Criterion: Coordinator can navigate all tabs and always see funding context

FR4: Dynamic Updates

  • Requirement: Funding balances reflect current state without requiring page refresh
  • Details:
    • When viewing Service Plan and making budget changes, funding updates after save
    • When navigating from Service Plan back to Overview, updated balances display
    • Updates use existing Inertia data flow (no new polling or WebSocket needed)
    • If budget plan changes status (approved → rejected), section updates or hides appropriately
  • Success Criterion: No manual refresh required; updates appear during normal navigation

FR5: Styling & Presentation

  • Requirement: Use existing FundingStreamBadge component styling and 2-column responsive layout
  • Details:
    • Reuse FundingStreamBadge.vue component colors and visual style
    • Grid layout: grid grid-cols-2 (2 badges per row) with responsive fallback to 1 column on mobile
    • Apply Tailwind gap utilities for spacing between badges (gap-3 or gap-4)
    • Support dark mode (inherit from sidebar styling)
    • Section title: “This Quarter’s Funding” with subtle font weight
    • Badge tooltip on hover shows: Full stream name + “Q3 2025” or date range
    • No 3-bar charts or utilization details (simplified vs. Service Plan view)
  • Success Criterion: Clean 2-column layout, responsive on mobile, full details in tooltips, visual consistency with existing funding UI

FR6: Empty State Handling

  • Requirement: Display elegant empty state when package has no active budget plan
  • Details:
    • Display section with centered message: “No Funding Streams”
    • Use subtle, professional styling to indicate no data (not an error state)
    • Section still displays as container (unlike pure hide approach) to show funding section is available feature
    • Recipient Information section and other sidebar content displays normally
    • When budget is created, section updates to show funding streams on next page view/tab navigation
  • Success Criterion: Users understand funding section exists but no active plan yet; clean, professional appearance

User Experience Flows

Flow 1: New User First Time Checking Funding

  1. Coordinator opens package Overview
  2. Sees Recipient Information (name, DOB, contact)
  3. Below that, immediately sees “Remaining balance by funding stream” with colored badges
  4. Quickly assesses: “ON has good funding, CM is low”
  5. Makes informed decisions about service allocation without tab switching

Flow 2: Coordinator After Modifying Budget

  1. In Service Plan, adjusts service levels and saves budget changes
  2. Funding allocations change as services are added/removed
  3. Navigates back to Overview or Care Circle tab
  4. Sidebar immediately shows updated funding balances
  5. Confirms changes were applied and proceeding with care planning

Flow 3: New Package With No Budget Yet

  1. Package created but budget plan not yet assigned
  2. Coordinator navigates to Overview
  3. Sidebar shows recipient info but no funding section (hidden)
  4. Clear signal: “Funding setup needed”
  5. Coordinator creates budget plan
  6. On next view/page load, funding section appears automatically

Data & Integration

Data Source

  • Primary Source: Current active (approved) budget plan’s funding streams
  • Calculation: Available balance from FundingStreamData entity (existing)
  • Timing: Populated during initial page load via PackageViewData
  • Updates: Reflected through Inertia re-renders when navigating between tabs

Key Entities

  • Package: Contains zero or more approved budget plans
  • BudgetPlan: Linked to single Package, contains multiple FundingStreams
  • FundingStream: External ID (ON, CM, etc.), colour, available amount, total funded, spent
  • FundingStreamData: DTO with availableAmount property (already exists)

Required Data Fields

  • Funding stream external ID (e.g., “ON”, “CM”)
  • Funding stream name (for accessibility/tooltips)
  • Funding stream colour (for badge styling)
  • Available amount (remaining balance)

Success Criteria

  1. Visibility: Funding balances visible on every package tab without navigation away from page
  2. Accuracy: Funding amounts match Service Plan view’s budget display within same session
  3. Consistency: Data updates automatically when budget changes (no manual refresh needed)
  4. Clean UX: No clutter; section hidden when no budget plan exists
  5. Performance: Sidebar loads with standard package view latency (no additional server requests)
  6. Accessibility: Badges include funding stream name for screen readers; colors not sole identifier
  7. Adoption: Care coordinators can identify funding context within 2 seconds of opening any package tab

Assumptions

  1. Single Active Plan Per Period: Only one approved budget plan is active per package per quarter/period
  2. Existing Data Available: FundingStreamData structure with availableAmount property exists and is reliable
  3. Package Metadata Flow: PackageViewData already distributed to all package view tabs
  4. Styling Available: FundingStreamBadge component colors and styles are reusable without modification
  5. No Real-Time Requirements: Updates acceptable during normal tab navigation (Inertia re-renders) without WebSocket polling
  6. Coordinate Display: If package has coordinator settings, funding display does not change based on coordination status

Edge Cases & Constraints

Edge Case 1: Package With No Budget Plan

  • Handling: Display “No Funding Streams” empty state message in sidebar section
  • User Experience: Clear signal that funding section is available but needs budget setup

Edge Case 2: Multiple Budget Plans in Different Quarters

  • Handling: Show only the active budget plan determined by Service Plan logic (Quarter Determination in FR2a)
  • Quarter Selection: Follows same priority as Service Plan—current quarter, then package commencement quarter, then plan commencement quarter
  • Result: Sidebar always shows same quarter/plan as Service Plan tab without user intervention

Edge Case 3: Budget Plan With Single Funding Stream

  • Handling: Display single badge in first position of 2-column grid (left side)
  • No special formatting needed, grid layout handles naturally

Edge Case 4: Funding Stream With Zero Balance

  • Handling: Display if part of active plan (e.g., “ON $0.00”)
  • Full name available in tooltip to provide context when amount is zero
  • No special styling for zero balances; existing system formatting applies

Edge Case 5: Large Currency Amounts (e.g., “$1,234,567.89”)

  • Handling: Currency formatting handles via existing format utilities
  • Constraint: Badge width may need responsive adjustment if amounts very large; full amount visible in tooltip if truncated

Edge Case 6: Very Long Funding Stream Names

  • Handling: Use external ID (ON, CM) as primary display; full name available via tooltip (FR1 requirement)
  • Tooltip Content: Full funding stream name visible on hover
  • Constraint: No text truncation within badges; badge shows code + amount only

Edge Case 7: Funding Stream With Negative Balance

  • Handling: Display if part of active plan (e.g., “ON -$500.00”)
  • No special styling for negative balances (system handles existing budget over-spending cases)
  • Future Enhancement: Could add warning indicator if needed in future iterations

Out of Scope

  • Detailed funding analytics: Utilization percentages, spent vs. forecast comparison (Service Plan view already provides this)
  • Funding modification: Cannot edit funding from sidebar (read-only display)
  • Funding history: No historical funding balances or trends in sidebar
  • Multiple budget plans comparison: Always shows current active plan only
  • Funding alerts: No warnings for low balances or expiring funds (future enhancement)
  • Coordination impact on display: Coordination settings don’t change funding display

Dependencies & Risks

Dependencies

  • Existing: FundingStreamData, FundingStreamBadge.vue, PackageViewData, PackageSidebar.vue
  • No new dependencies required

Risks

  • Data Accuracy: If funding calculations in budget plan are incorrect, sidebar displays incorrect data (inherited risk, not new)
  • Stale Data: If user has multiple browser tabs open, sidebar in one tab may show stale funding (Inertia re-render on focus could mitigate)

Mitigation

  • Ensure tests verify funding amounts match Service Plan view
  • Document assumption that current active plan is reliable source
  • Monitor bug reports for funding accuracy issues

Clarifications

Session 2025-12-09

Clarification 1: Quarter Determination Logic

  • Q: How should the system determine which quarter’s funding to display?
  • A: Follow the same logic as Service Plan controller—use Quarter::getCurrent() if available in selectable range, else package commencement quarter, else plan commencement quarter. This ensures sidebar always shows the same quarter as the Service Plan tab.
  • Impact: Implemented in FR2a (Quarter Determination)

Clarification 2: Tooltip Content for Funding Stream Badges

  • Q: What information should be in badge tooltips?
  • A: Full funding stream name (beyond the short code like “ON” or “CM”) should be visible in tooltip. Additional quarter/date context available in tooltip as well.
  • Impact: Updated FR1 to include tooltip requirement

Clarification 3: Active Budget Plan Definition

  • Q: Should sidebar show only the current active plan, or aggregate multiple plans?
  • A: Only the active (single) budget plan for the determined quarter. No aggregation across multiple plans.
  • Impact: Updated FR2 to clarify “only the active budget plan”

Clarification 4: Empty State Presentation

  • Q: When no budget plan exists, hide the section or show empty state?
  • A: Display a beautiful “No Funding Streams” empty state message. Section visible but with graceful empty state, not hidden.
  • Impact: Updated FR6 and Edge Case 1 to show “No Funding Streams” message

Clarification 5: Funding Stream Badge Layout

  • Q: How should multiple funding streams be arranged in the sidebar?
  • A: Stack them vertically (no maximum count). All available funding streams displayed.
  • Impact: Updated FR1 to require vertical stacking; removed 6-8 maximum limit

Clarification 6: Redundant Display on Service Plan Tab

  • Q: Should funding section display on Service Plan tab when detailed budget view already shows it?
  • A: Yes, intentionally redundant. Service Plan tab will show both sidebar summary and detailed budget view for consistency and context awareness.
  • Impact: Updated FR2 to document intentional redundancy

Clarification 7: Layout and Quarter Display (Design Version B)

  • Q: How should funding badges be arranged? Should quarter be displayed?
  • A: Two-column horizontal grid layout (2 badges per row, wrapping on narrow screens). Section label: “This Quarter’s Funding” (no explicit quarter date). Badge format: code + amount only (e.g., “ON $25,000”). Full stream name and quarter details in tooltip on hover.
  • Impact: Updated FR1 and FR5 to reflect 2-column grid layout; changed section title to “This Quarter’s Funding”; tooltip now contains all detailed information

Next Steps

  1. Design Review: Validate layout matches version B mockup, confirm badge positioning and spacing
  2. Clarify Edge Cases: Confirm handling for “current quarter” determination and negative balance display
  3. Plan Development: Create technical plan for backend and frontend implementation
  4. Mockup Refinement: Generate interactive mockups showing all scenarios (no funding, single stream, multiple streams)
  5. Acceptance Testing: Develop test cases for each user story and edge case