Skip to content
Trilogy Care Logo TC Docs

Budget Wraparound Services - Brain Dump

Budget Wraparound Services - Brain Dump

Created: 2025-11-04 Status: Feature Planning Phase Epic: TP-XXXX-wai-budget-wraparound (under TP-1869-budgets-and-services) Product Owner: Matthew Business Analyst: Dave

Feature Overview

What: Workflow for identifying, flagging, and linking wraparound services (installation, delivery, setup, training) to their related equipment items in bill processing.

Why:

  • Reduce cognitive load for Philippines bill processing team
  • Ensure correct classification to Services Australia API (itemOrWraparound field)
  • Support cross-invoice scenarios where wraparound arrives on separate invoice from equipment
  • Improve financial tracking of total equipment cost (equipment + all wraparound services)

Value: ~$66,000/year (time savings + error reduction)

Key Problem Scenarios

Scenario A: Same Invoice (Common)

Invoice #INV-123:
  Line 1: Walker ($800)
    → ITEM type
    → Belongs to: Equipment Plan Service #567
    → Funding: AT


  Line 2: Walker Installation ($100)
    → WRAPAROUND type
    → Related to: Line 1 (Walker)
    → Funding: AT (inherited)

Scenario B: Different Invoices (Edge Case - Critical!)

Invoice #INV-123 (Oct 15):
  Line 1: Walker ($800)
    → ITEM type
    → Belongs to: Equipment Plan Service #567
    → Funding: AT


Invoice #INV-456 (Oct 22, submitted later):
  Line 1: Walker Delivery & Setup ($150)
    → WRAPAROUND type
    → Links back to: Invoice #INV-123, Line 1
    → Belongs to: Equipment Plan Service #567
    → Funding: AT (inherited)

Key insight: Must support cross-invoice linking because supply chain timings mean wraparound services are often invoiced separately.

Solution Approach

Track at Bill Item Level (not plan service level):

  1. New Fields on BillItem Model:

    • is_wraparound: boolean - Is this item a wraparound service?
    • wraparound_type: enum - Installation, Delivery, Setup, Training, Other
    • related_bill_item_id: foreign_key - Links to the equipment bill item
    • wrapped_equipment_description: text - What equipment does this wrap? (free text)

  2. Linking Mechanism:

    • User selects “Flag as Wraparound” on bill item
    • System shows recent equipment items from same package (last 90 days)
    • User selects which equipment item this wraps
    • System validates that both items will code to same plan service item + funding stream
    • Wraparound automatically inherits funding allocation from equipment

  3. Services Australia API Integration:

    • Map is_wraparound=true → itemOrWraparound="WRAPAROUND"
    • Populate wraparoundDescriptionCode (from reference data)
    • Populate wraparoundDescriptionText (free text description)
    • Both equipment and wraparound items appear on same SA invoice

Stakeholders & RACI

Core Team

RoleNameDepartmentInvolvement
Product OwnerMatthewProduct/ExecutiveAccountable for scope, go/no-go, prioritization
Business AnalystDaveProduct/BusinessResponsible for requirements gathering, PRD, UAT planning
DesignerBruceUX/DesignResponsible for UI/UX workflow, wireframes, bill item interface
Backend DeveloperRomyEngineeringConsulted on architecture, database design
Frontend DeveloperWillEngineeringConsulted on UI implementation, state management
Finance LeadFRANFinanceConsulted on budget/funding rules, AT/HM allocation
Bill Processing LeadMELLETTEAccounts Payable (Philippines)Consulted on user workflow, Responsible for UAT & training delivery
ComplianceSOPHIEComplianceConsulted on Services Australia API requirements
Finance AnalystMARKOFinanceInformed on budget tracking, reporting

Consulted Group Summary

  • Matthew - PO (Accountable)
  • Dave - BA (Responsible for PRD, Consulted on decisions)
  • Romy - Backend (Consulted on architecture)
  • Will - Frontend (Consulted on UI)
  • Bruce - Designer (Responsible for UI/UX)
  • FRAN - Finance Lead (Consulted on funding rules)
  • MELLETTE - Philippines Lead (Consulted on workflow, Responsible for training)
  • SOPHIE - Compliance (Consulted on SA API)

Informed

  • MARKO - Finance Analyst
  • Care Partners (PAT, SIAN) - May review complex wraparound scenarios
  • Equipment Providers (external)
  • Support Team - Tier 2 support for edge cases

Edge Cases & Open Questions

Edge Cases

  1. Wraparound arrives before equipment (LOW probability)

    • Solution: Allow “pending link” state, resolve when equipment invoice arrives

  2. Multiple wraparound items for one equipment (NORMAL)

    • Example: Walker + Installation + Training + Delivery (4 invoices)
    • Solution: Support 1:many relationship (one equipment → multiple wraparounds)

  3. Wraparound on different supplier invoice (NORMAL)

    • Example: Equipment from ABC Medical, delivery from XYZ Logistics
    • Solution: Cross-invoice linking handles this

  4. Wrong wraparound linked to wrong equipment (ERROR)

    • Solution: Add UI warning if linking seems odd (e.g., walker installation for orthotics)
    • QA/testing to catch

Open Questions (For PRD Phase)

  1. What is the official Services Australia definition of a “wraparound service”?

    • Is it only AT/HM specific or broader?
    • Are there other service groups that need wraparound support?

  2. What are the specific wraparoundDescriptionCode reference data values?

    • Installation, Delivery, Setup, Training, Other?
    • Are there additional codes from SA?

  3. Is itemOrWraparound field mandatory for all AT/HM items or only when present?

    • If equipment has no wraparound, is it “ITEM” or left empty?

  4. Should there be budget allocation separate from equipment?

    • Example: $800 equipment + $100 installation = $900 total to plan item?
    • Or should they be tracked separately?

  5. Are there limits on how many wraparound services can link to one equipment item?

    • Practical limit or unlimited?

  6. What if wraparound service value exceeds a threshold?

    • Should care partner approval be required for high-value wraparounds?

Services Australia API Context

From .claude/BRAIN/Industry/Aged Care/services-australia-api.md:

Item Fields

Each invoice item has:

itemOrWraparound: "ITEM" | "WRAPAROUND"
wraparoundDescriptionCode: string (e.g., "WRAP-001")
wraparoundDescriptionText: string (e.g., "Installation")
wraparoundDescription: string (free text, 500 chars)

Funding Source Rules

  • AT/HM items can have wraparound services
  • Wraparound services use same funding source as equipment
  • Both items submitted together in same invoice to SA

Submission Pattern

  1. Create invoice with multiple items
  2. Some items are ITEM type (equipment)
  3. Some items are WRAPAROUND type (related services)
  4. Submit single invoice to SA
  5. SA system validates relationships between items

Bill Processing Context

From .claude/BRAIN/Features/bill-processing.md:

Current Workflow

  1. Bill arrives from supplier
  2. BPO matches line items to service plan items
  3. Matching criteria: supplier, service type, rate, date range, funding stream
  4. BPO processes as planned or flags as unplanned
  5. Care partner approves if unplanned
  6. Bill approved and queued for payment

This Feature Adds

  • Before step 3: Check if line item is wraparound
  • If yes: Find equipment it wraps (same invoice or different)
  • Link wraparound to equipment item
  • Inherit plan service item + funding from equipment
  • Rest of workflow continues as normal

Technical Architecture (High Level)

Database Changes

-- Bill Items table
ALTER TABLE bill_items ADD COLUMN is_wraparound BOOLEAN DEFAULT FALSE;
ALTER TABLE bill_items ADD COLUMN wraparound_type ENUM('Installation', 'Delivery', 'Setup', 'Training', 'Other');
ALTER TABLE bill_items ADD COLUMN related_bill_item_id BIGINT UNSIGNED NULLABLE;
ALTER TABLE bill_items ADD FOREIGN KEY (related_bill_item_id) REFERENCES bill_items(id);
ALTER TABLE bill_items ADD COLUMN wrapped_equipment_description TEXT NULLABLE;

Domain Actions (Laravel)

  • FlagBillItemAsWraparound - Set is_wraparound flag
  • LinkWraparoundToEquipment - Create cross-invoice link
  • InheritFundingFromEquipment - Copy funding allocation
  • ValidateWraparoundLinking - Check both items code to same plan service

Services Australia API Integration

  • Map is_wraparound → itemOrWraparound field
  • Populate wraparound code/text when submitting to SA API
  • Update invoice export logic for SA format

UI Components (Vue 3/Inertia)

  • Wraparound flag toggle on bill item form
  • Equipment item lookup/search interface (with date range filter)
  • Visual link indicator showing related items
  • Inherited funding stream display

Effort Estimate

4-5 sprints / 8-10 weeks / 40-50 story points

Breakdown:

  • Sprint 1-2: Database schema, actions, validation (Backend)
  • Sprint 2-3: Bill item UI, wraparound workflow, cross-invoice linking (Frontend)
  • Sprint 3-4: Services Australia API integration, test environment validation
  • Sprint 4-5: QA, UAT with Philippines team, training materials, production deployment

Success Metrics

  1. Adoption: 100% of AT/HM wraparound invoices properly flagged within 30 days of launch
  2. Accuracy: Zero misclassified wraparound items in first 100 invoices
  3. Processing Time: Average wraparound processing time < 2 minutes (down from 5 minutes manual)
  4. Error Reduction: Prevent 10+ misallocations per month
  5. SA API Compliance: 100% correct itemOrWraparound field population
  6. User Satisfaction: Philippines team rates UI as “Easy” or “Very Easy” (80%+ adoption)
  7. Training Effectiveness: 95%+ of team completes training successfully
  8. No Cross-Invoice Errors: Zero incidents of wraparound linked to wrong equipment

Risk Mitigation

RiskSeverityMitigation
Cross-invoice lookup is complexHIGHLimit search to 90 days, same package; caching for performance
Wraparound before equipment arrivesMEDAllow “pending link” state; reminder system to resolve
Training adoption issuesMEDComprehensive training, clear UI prompts, dedicated support
SA API validation failsMEDExtensive test environment validation before production
Confusion about wraparound definitionLOWClear documentation, examples, internal wiki
Performance impact with many linked itemsLOWDatabase indexing on related_bill_item_id, query optimization

Dependencies

External (Hard Blockers)

  • Services Australia API test environment available
  • SA reference data for wraparoundDescriptionCode values
  • Clarification on SA API wraparound requirements (open questions above)

Internal

  • Existing bill processing UI (extend for wraparound)
  • Budget plan item model (must code to correct plan service)
  • Funding stream allocation logic (AT/HM rules)

Team Dependencies

  • Bill Processing Team available for requirements gathering & UAT
  • Bruce (Designer) available for UI/UX work
  • Backend dev capacity for database schema + actions
  • Frontend dev capacity for Vue components

Files & References

Epic Documentation:

  • .trilogy/initiatives/TP-1869-budgets-and-services/TP-XXXX-wai-budget-wraparound/idea.md
  • .trilogy/initiatives/TP-1869-budgets-and-services/TP-XXXX-wai-budget-wraparound/RACI.md
  • .trilogy/initiatives/TP-1869-budgets-and-services/TP-XXXX-wai-budget-wraparound/PRD.md (to be created)
  • .trilogy/initiatives/TP-1869-budgets-and-services/TP-XXXX-wai-budget-wraparound/USER-STORIES/user-stories.csv (to be created)

Reference Documentation:

  • .claude/BRAIN/Features/bill-processing.md - Bill processing workflows
  • .claude/BRAIN/Industry/Aged Care/services-australia-api.md - SA API details
  • .claude/BRAIN/1. OVERVIEW/1-context-portal.md - TC Portal architecture
  • .claude/BRAIN/1. OVERVIEW/4-departments-and-stakeholders.md - Team structure

Timeline (Rough)

  • Week 1-2: Requirements gathering (Dave), design kickoff (Bruce)
  • Week 2-3: PRD creation, architecture planning (Romy)
  • Week 3-5: Backend development (database, actions, validation)
  • Week 4-6: Frontend development (UI components, linking flow)
  • Week 5-7: SA API integration, test environment validation
  • Week 7-8: QA, UAT with Philippines team, bug fixes
  • Week 8-9: Training materials, training delivery
  • Week 9-10: Production deployment, monitoring

Communication Cadence

Weekly Standup: Monday 9 AM (Matthew, Dave, Romy, Will, Bruce) Weekly Status: Friday 3 PM (+ FRAN, MELLETTE, SOPHIE) Bi-weekly Architecture Review: Every other Wednesday (Engineers + Romy) Monthly Product Review: End of month (Matthew + stakeholders) UAT Kickoff: 2 weeks before launch (Dave, MELLETTE, QA team)

Next Steps

  1. Approve This Brain Dump & Stakeholder List → Matthew decision
  2. Schedule PRD Kickoff → Dave to facilitate with Matthew, Romy, Will, Bruce
  3. Design Workshop → Bruce to create wireframes (1 week)
  4. Create Detailed PRD → Dave with input from team (1-2 weeks)
  5. Architecture Review → Romy + Devs to finalize technical approach (1 week)
  6. Break into User Stories → Create user-stories.csv under epic folder
  7. Jira Import → Create epic in Jira with linked stories

Notes & Decisions

  • Bill Item Level vs. Plan Service Level: Chosen bill item level because:

    • Supports cross-invoice scenarios better
    • More granular tracking
    • Each wraparound can have different type/date/supplier
    • Easier to track which specific items are bundled together

  • No Separate Budget Allocation: Wraparound services inherit equipment budget line because:

    • Reduces complexity for bill processors
    • Total equipment cost (equipment + wraparound) against single plan item makes sense
    • Reflects how budget is actually created (plan service item, not per-service-component)

  • Philippines Team as “Consulted” (Not Responsible): Because:

    • We’re designing the UI for them
    • They execute the workflow (check box, link item, done)
    • They’re not responsible for technical implementation, but their input is critical

  • SOPHIE (Compliance) as Consulted: Because:

    • Must ensure SA API compliance
    • Wraparound field requirements come from external API spec
    • Should review PRD and test cases before implementation

Last Updated: 2025-11-04 Status: Ready for PRD phase Owner: Matthew (PO) + Dave (BA)