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

Medication Plan System

Overview

The Collabree medication plan system manages patient adherence programs through a structured workflow involving Azure authentication, organization enrollment, and plan definition transformation. This document explains the complete flow from patient registration to care plan activation.

System Architecture

Core Components

  1. Patient Registration - Azure Entra ID authentication
  2. Organization Selection - Healthcare provider enrollment
  3. Plan Definition - Template plans with adherence parameters
  4. Care Plan - Active patient-specific plans
  5. Medication Management - Individual medication tracking

Patient Registration Flow

1. Azure Entra ID Authentication

Patients begin by authenticating through Azure Entra ID. The fire-arrow service is responsible for automatically provisioning patients in the database upon successful authentication.

Key Points:

  • Patient identity is managed through Azure Entra ID
  • Upon successful authentication, a CollabreePatient resource is created
  • The fire-arrow service automatically provisions patients in the database
  • Patient must have a valid email address in their Azure profile
  • Timezone information is captured for proper medication scheduling

2. Organization Selection

After authentication, patients must select their healthcare organization. The system loads available organizations, the patient selects one, the patient is linked to the organization, and then organization plan definitions become available.

Organization Structure:

  • Root Organizations: Top-level healthcare providers (e.g., insurance companies)
  • Customer Organizations: Specific healthcare entities under root organizations
  • Each organization has two plan types: Primary and Fallback

Plan Definition System

Plan Types

Each organization maintains two distinct plan definitions:

Primary Plan Definition
  • Purpose: Main adherence program for active patients (payable period)
  • Duration: Defined period (e.g., 90 days) with specific start and end dates
  • Parameters: Full adherence tracking configuration
  • Activation: Applied when patient adds first medication
  • Rewards: Monetary rewards based on adherence performance
Fallback Plan Definition
  • Purpose: Continuation program after primary plan completion
  • Duration: Ongoing (no end date)
  • Parameters: Modified adherence parameters (typically points-based)
  • Activation: Automatically starts when primary plan ends
  • Rewards: No rewards and claims generated for this plan

Plan Definition Parameters

Both plan types include

  • Adherence Tracking extensions
  • Medication catalog country provider
{
  "extension": [
    {
      "url": "https://fhir.collabree.com/Extensions/initial-balance",
      "valueDecimal": 100
    },
    {
      "url": "https://fhir.collabree.com/Extensions/balance-currency", 
      "valueString": "CHF"
    },
    {
      "url": "https://fhir.collabree.com/Extensions/payout-period-in-days",
      "valueInteger": 30
    },
    {
      "url": "https://fhir.collabree.com/Extensions/loss-per-day",
      "valueDecimal": 4.0
    },
    {
      "url": "https://fhir.collabree.com/Extensions/cheat-days",
      "valueInteger": 3
    },
    {
      "url": "https://fhir.collabree.com/Extensions/adherence-threshold",
      "valueDecimal": 0.99
    },
    {
      "url": "https://fhir.collabree.com/Extensions/number-of-payouts",
      "valueInteger": 3
    }
    {
      "url": "https://fhir.collabree.com/Extensions/country-code",
      "valueString": "CH"
    }
  ]
}

Parameter Descriptions:

  • Initial Balance: Starting monetary reward amount
  • 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 plan
  • CountryCode: Medication catalog country code for this plan

Care Plan Transformation

Activation Trigger

A CarePlan is created when a patient adds their first medication. The system uses the PlanDefinition $apply operation to transform the selected PlanDefinition (primary or fallback) into an active CarePlan for the patient.

Transformation Process

  1. Plan Selection: System determines which plan definition to use (primary if available, otherwise fallback)
  2. PlanDefinition Apply: The PlanDefinition $apply operation is invoked to transform the PlanDefinition template into a patient-specific CarePlan
  3. Resource Creation: CollabreeCarePlan is instantiated through the apply operation
  4. Extension Application: All adherence tracking extensions are copied from the plan definition
  5. Patient Linking: CarePlan is linked to the authenticated patient
  6. Medication Request Association: MedicationRequest resources are linked to the CarePlan
  7. Recalculation: Extensions are recalculated and updated during adherence processing

Care Plan Structure

{
  "resourceType": "CarePlan",
  "status": "active",
  "intent": "proposal",
  "title": "Collabree Medication Plan",
  "subject": {
    "reference": "Patient/[patient-id]"
  },
  "instantiatesCanonical": [
    "PlanDefinition/[plan-definition-id]"
  ],
  "period": {
    "start": "2025-10-21T08:44:30.614689Z",
    "end": "2026-01-19T08:44:30.614689Z"
  },
  "activity": [
    {
      "reference": {
        "reference": "MedicationRequest/[medication-request-id]"
      }
    }
  ]
}

Period Configuration:

  • Primary Plans: Include both start and end dates (payable periods)
  • Fallback Plans: Include only start date (ongoing periods)
  • Duration: Primary plan duration matches the plan definition's therapy duration

Plan Lifecycle Management

Primary Plan Lifecycle

The primary plan starts when the patient adds their first medication. During the plan period, adherence tracking is active. Once the plan period ends, final rewards are calculated and the system automatically transitions to the fallback plan.

Fallback Plan Lifecycle

The fallback plan starts when the primary plan ends. It provides points-based rewards with ongoing medication tracking and continuous adherence monitoring, with periodic reward calculations throughout the plan's lifecycle.

Implementation Considerations

Data Flow

  1. Patient Registration: Azure Entra ID → CollabreePatient
  2. Organization Enrollment: Patient selects organization → managingOrganization set
  3. Plan Availability: Organization plan definitions become accessible
  4. Medication Addition: First medication triggers CarePlan creation
  5. Adherence Tracking: Daily Observation resources track medication adherence

Security Considerations

  • Patient Data Isolation: Each patient only sees their own data. This isolation is enforced through fire-arrow's RBAC (Role-Based Access Control) validation, which ensures that users can only access resources they are authorized to view.
  • Organization Boundaries: Patients can only access their organization's plans
  • Azure Integration: Authentication handled securely through Microsoft services
  • FHIR Compliance: All data structures follow FHIR R4B standards

Required FHIR Resources

  1. Patient: Patient profile with timezone and organization
  2. Organization: Healthcare provider with plan definitions
  3. PlanDefinition: Template plans with adherence parameters
  4. CarePlan: Active patient-specific plans
  5. MedicationRequest: Individual medication prescriptions
  6. Observation: Daily adherence tracking data

Business Rules

  1. One Active CarePlan: Patients can only have one active CarePlan at a time
  2. Plan Transition: Automatic transition from primary to fallback plans
  3. Organization Dependency: All plan operations require valid organization
  4. Medication Trigger: CarePlan creation requires at least one medication
  5. Adherence Calculation: Daily Observation resources track adherence scores and streaks