collabreefhirdocumentation - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Adherence Calculation System
Overview
The Collabree adherence calculation system is a sophisticated engine that processes patient medication adherence data to generate scores, streaks, and reward balances. This system operates through both scheduled cron jobs and real-time webhook processing to ensure accurate and timely adherence tracking.
This adherence calculation system ensures accurate, timely, and consistent tracking of patient medication adherence while providing comprehensive reward mechanisms and detailed analytics for healthcare organizations.
Core Components
- Daily Adherence Processor - Core calculation engine
- Cron Service - Scheduled batch processing
- Webhook Service - Real-time event processing
- Observation Resources - Daily adherence tracking data with extensions for calculation results
Adherence Calculation Engine
Processing Modes
1. Scheduled Processing (Cron)
- Service:
adherence-processor-cron
- Frequency: Every 3 hours
- Scope: All patients with active and non expired care plans
- Purpose: Comprehensive adherence calculations
2. Real-time Processing (Webhook)
- Service:
adherence-processor-webhook
- Triggers:
- MedicationRequest created, modified, or deleted
- Patient takes medication (MedicationStatement created)
- Patient untakes medication (MedicationStatement deleted/modified)
- Scope: Individual patient processing
- Purpose: Immediate adherence updates
Calculation Parameters
The adherence calculation system uses configurable parameters defined in plan definitions:
{
"initialBalance": 100.0,
"balanceCurrency": "CHF",
"payoutPeriodInDays": 30,
"lossPerDay": 4.0,
"cheatDays": 3,
"adherenceThreshold": 0.99,
"numberOfPayouts": 3
}
Parameter Descriptions:
- Initial Balance: Starting reward amount for new patients
- Balance Currency: Currency code (CHF, EUR, USD, or XXX for points)
- Payout Period: Days between reward calculations
- Loss Per Day: Amount deducted for missed doses
- Cheat Days: Number of allowed missed days per period
- Adherence Threshold: Minimum adherence percentage for rewards
- Number of Payouts: Total payout cycles in primary plan
Adherence Metrics
Daily Adherence Score
- Range: 0.0 to 1.0 (normalized)
- Calculation: Based on medication intake timing and completeness
- Storage:
DailyAdherenceScoreCalculation extension
- Update Frequency: Every 3 hours, or whenever user updates/creates/deletes medication statement/request
Total Adherence Score
- Range: 0.0 to 1.0 (normalized)
- Calculation: Cumulative adherence across all tracked days inside 1 payout period defined in
effectiveTiming.repeat.boundsPeriod
- Storage:
TotalAdherenceScoreCalculation extension
- Update Frequency: Every 3 hours, or whenever user updates/creates/deletes medication statement/request
Best Adherence Score
- Range: 0.0 to 1.0 (normalized)
- Calculation: Highest adherence score achieved
- Storage:
BestAdherenceScoreCalculation extension
- Update Frequency: When new best score is achieved
Streak Calculations
Daily Streak
- Type: Current consecutive days of perfect adherence
- Storage:
DailyStreakCalculation extension
- Reset: When adherence falls below threshold
Best Streak
- Type: Longest consecutive days of perfect adherence
- Storage:
BestStreakCalculation extension
- Update: When new longest streak is achieved
Balance Calculation
- Type: Monetary reward balance
- Storage:
BalanceCalculation extension
- Components: Initial balance minus daily losses
- Currency: Configurable per organization
Webhook Triggers
MedicationRequest Events
The webhook is triggered when MedicationRequest resources are:
- Created: New medication prescribed to patient
- Modified: Changes to existing medication prescriptions
- Deleted: Medication prescriptions removed or discontinued
MedicationStatement Events
The webhook is triggered when MedicationStatement resources are:
- Created: Patient takes medication (adherence recorded)
- Modified: Changes to medication intake records
- Deleted: Patient untakes medication (adherence removed)
Event Processing Logic
- Immediate Processing: Webhook triggers instant adherence recalculation
- Patient-Specific: Only processes the affected patient's data
- Incremental Updates: Updates only changed adherence metrics
- Consistency: Ensures data consistency across all adherence calculations
Processing Flow
Scheduled Processing
The cron service runs every 3 hours and processes all patients with active and non-expired care plans. For each patient, it loads medication requests and statements, calculates daily adherence scores, updates streak counters, calculates balance changes, and updates observation resources.
Real-time Processing
The webhook service triggers immediately when MedicationRequest or MedicationStatement resources are created, modified, or deleted. It validates the patient role, extracts the patient ID, loads patient data, processes recent medication events, recalculates adherence metrics, and updates FHIR resources.
FHIR Resource Integration
Observation Resources
Daily adherence data is stored in Observation resources with:
- Category:
original or snapshot
- Code: LOINC code
71799-1 (Adherence to prescribed medication instructions)
- Components: Daily adherence records with calculated metrics
- Extensions: All calculated adherence scores and streaks
Extension Usage
Plan Definition Extensions
Applied to PlanDefinition and CarePlan:
Observation Extensions
Applied to daily Observation components:
Business Rules
Adherence Thresholds
- Perfect Adherence: Score = 1.0
- Acceptable Adherence: Score ≥ adherence threshold
- Poor Adherence: Score < adherence threshold
Cheat Day Logic
- Grace Period: First N missed days don't affect balance
- Penalty Application: Additional missed days reduce balance
- Streak Reset: Any missed day resets current streak
Balance Management
- Initial Balance: Set at plan start
- Daily Deductions: Applied for non-adherence
- Payout Calculation: Based on period adherence
- Currency Handling: Supports multiple currencies and points