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

Trophy System

Overview

The trophy system gamifies medication adherence by awarding achievements for patient progress across multiple dimensions of care. Trophies are organized into five distinct categories based on patient behavior and engagement, providing positive reinforcement and motivation throughout the treatment journey. All unlocked trophies are persisted as FHIR Goal resources with completed lifecycle status, enabling comprehensive tracking of patient achievements across devices and sessions.

Trophy Categories

The trophy system features 22 distinct trophies organized into five categories that recognize different aspects of patient engagement with their medication regimen.

Perfect Days

Rewards 100% medication adherence: 1, 7, 14, 28, and 90 perfect days. Perfect days are calculated by counting days where the daily adherence score is exactly 1.0, indicating that all scheduled medications were taken as prescribed without any missed doses.

Trophy IDs:

• perfect-day-1
• perfect-day-7
• perfect-day-14
• perfect-day-28
• perfect-day-90

Streak Trophies

Celebrates consecutive days of adherence. A streak represents unbroken consecutive days where medication was taken. The system tracks the best streak achieved, which may not necessarily be the current streak, allowing patients to receive recognition for past achievements even if their current streak is broken. Awarded for streaks of 3, 5, 10, 20, and 30 days.

Trophy IDs:

• streak-3
• streak-5
• streak-10
• streak-20
• streak-30

Medication Adherence Above 80%

Recognizes weeks of strong adherence above 80%: 1, 2, 4, and 8 consecutive weeks. While perfect adherence is ideal, maintaining adherence above 80% represents excellent medication management and is clinically significant for treatment effectiveness. This category provides more achievable targets than perfect adherence while still encouraging high-quality medication management, making it particularly valuable for patients with complex medication regimens where perfect adherence may be challenging.

Trophy IDs:

• adherence-above-80-percent-for-1-week
• adherence-above-80-percent-for-2-weeks
• adherence-above-80-percent-for-4-weeks
• adherence-above-80-percent-for-8-weeks

Special Achievements

Milestones for fundamental engagement in treatment.

Trophy IDs:

• special-plan-added - Awarded when the first care plan is added to the system
• special-reminder-activated - Awarded when medication reminder permission is activated

Knowledge Trophies

Rewards for completing quizzes: 5, 10, 20, 40, and 60 completions. These trophies encourage patients to learn about their medications, treatments, and health conditions, recognizing that knowledge is a key component of effective self-management. The progression from Student to Wizard creates a clear learning journey, with increasingly prestigious titles motivating continued engagement with educational content.

Trophy IDs:

• knowledge-student - 5 quizzes completed
• knowledge-master - 10 quizzes completed
• knowledge-professor - 20 quizzes completed
• knowledge-genius - 40 quizzes completed
• knowledge-wizard - 60 quizzes completed

Trophy Calculation and Synchronization

Trophy awards are automatically calculated on app side and synchronized by the trophy system, which continuously monitors patient behavior across multiple data sources. The system listens to changes in adherence observations, quiz completions, medication plan state, and notification preferences to automatically determine which trophies have been earned.

The synchronization process uses an event queue to ensure that trophy calculations occur in a controlled, sequential manner, preventing race conditions and ensuring accurate trophy state. When changes are detected in any monitored cubit, the system automatically triggers a sync operation that recalculates earned trophies based on current patient data.

Trophy Storage and Persistence

All unlocked trophies are stored as FHIR Goal resources with their lifecycle status set to completed. Each Goal resource uses a custom identifier system where the identifier system is the trophy value set URL (https://fhir.collabree.com/fhir/ValueSet/trophy) and the identifier value is the trophy type string in FHIR format (e.g., "perfect-day-7", "streak-10", "knowledge-wizard"). This identifier structure allows the system to uniquely identify each trophy and determine which trophies have already been unlocked, preventing duplicate trophy creation.

The subject reference on each Goal resource links the trophy to the patient who earned it, enabling patient-specific trophy collections. The description field uses SNOMED CT coding (code "404684003" from the system http://snomed.info/sct with display "Clinical finding (finding)") to provide semantic meaning to the trophy within the FHIR framework, allowing external systems to understand that trophies represent clinical achievements.

Upon initialization, the TrophyCubit retrieves all existing trophy Goals for the current patient from the server, loading their trophy collection into the application state. When new trophies are calculated during synchronization, only trophies that haven't already been persisted are created as new Goal resources, ensuring that trophy achievements are permanently recorded in the patient's health record while avoiding redundant database entries.