0.1.0 - ci-build

collabreefhirdocumentation - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Payout Processor System

Overview

The Payout Processor is a critical component of Collabree's adherence-as-a-service platform that automatically generates financial claims based on patient medication adherence performance. It processes adherence observations and creates FHIR Claim resources for monetary rewards.

It operates on a periodic basis, analyzing patient adherence data and generating payouts according to predefined plan definitions. It ensures that patients receive appropriate financial rewards based on their medication adherence performance while maintaining audit trails through FHIR resources.

We are not handling any real money payout mechanism is just creating a Claim entity

Core Components

1. PayoutProcessor Class

  • Purpose: Central orchestrator and state manager for payout processing
  • Responsibilities:
    • State Management: Tracks observation status and payout counts
    • Period Orchestration: Groups daily observations into configurable periods
    • Resource Coordination: Manages FHIR resource lifecycle (Claims, Coverage, Observations)
    • Audit Trail: Maintains complete processing history

2. Payout Calculation Engine

  • Purpose: Financial calculation engine with penalty-based reward system
  • Algorithm: Sophisticated penalty system with grace periods and thresholds
  • Input Validation: Ensures adherence scores are within valid ranges
  • Output: Normalized payout values (0.0 to 1.0) for currency-agnostic processing

Processing Flow

The Payout Processor processes adherence observations and generates payouts according to the configured plan definitions. The processor groups daily observations into payout periods, validates period completeness, creates snapshot observations for audit trails, manages coverage resources, and generates Claim resources with the calculated payout amounts.

FHIR Resource Management

Claim Creation

Each payout generates a CollabreeClaim with:

  • Status: active
  • Type: institutional
  • Supporting Info: Reference to snapshot observation
  • Patient: Reference to patient
  • Provider: Reference to managing organization
  • Insurance: Reference to coverage
  • Total: Calculated payout amount
  • Billable Period: Period start and end dates

Observation Snapshots

  • Purpose: Permanent audit trail for claims
  • Status: Set to final
  • Category: Added snapshot version type
  • Based On: Links to original observation
  • Supporting: Evidence for claim processing

Plan Definition Extensions

The processor uses several extensions from PlanDefinition. Configuration parameters are read from PlanDefinition rather than CarePlan because PlanDefinition resources are immutable by the client, ensuring that payout calculations use the correct, unmodified parameters: