Product User Guide

Documentation and help for Medaius Clinic System

Care Team Domain - Workflow Narrative

A conversational guide to understanding care coordination workflows

What is the Care Team Domain?

Healthcare is rarely delivered by a single provider. A patient might have a primary care physician, a specialist, a nurse care manager, a physical therapist, and a social worker - all involved in their care.

The Care Team domain manages these multi-provider relationships. It tracks who is involved in a patient's care, what their role is, and how they should be notified about clinical changes.

The FHIR Foundation

FHIR CareTeam Resource

The care team model follows the FHIR (Fast Healthcare Interoperability Resources) standard. This isn't just academic - it means the data structures can interoperate with other healthcare systems that follow FHIR.

Key concepts from FHIR:

  • A care team is formed around a subject (patient)
  • Teams have a status lifecycle
  • Teams have participants with defined roles
  • Each participant has a validity period

Creating a Care Team

When Teams Are Formed

Care teams are typically created when a patient's care requires coordination. Common triggers:

  • Patient has a chronic condition requiring multiple specialists
  • Patient is transitioning between care settings
  • Organization policy requires care teams for all patients

The Creation Flow

The CareTeamService.create_care_team() method accepts:

  • patient_id - Which patient this team serves
  • name - Descriptive name ("John's Cardiac Care Team")
  • category - Type of team (longitudinal, episode, encounter)
  • status - Usually "proposed" or "active"
  • reason_text - Why this team was formed
  • organization_id - Scoping to an organization

Category Types

  • longitudinal - Ongoing care team, no end date
  • episode - For a specific care episode (e.g., post-surgery recovery)
  • encounter - Just for a single visit
  • condition - Focused on managing a specific condition

Activity Event

Creating a care team triggers a CARE_TEAM_CREATED event. This notifies relevant users that coordination has been established for this patient.

Adding Team Participants

Who Can Participate

Participants can be:

  • Practitioners - Doctors, nurses, therapists
  • Organization members - Administrative coordinators
  • External references - Non-system participants (family caregivers noted by name)

The Add Flow

add_participant() takes:

  • care_team_id - Which team to join
  • member_id - User or practitioner ID
  • role - Their role on the team (lead, member, consultant)
  • onboarding_date - When they joined
  • offboarding_date - Optional end date

Role Types

  • lead - Primary coordinator, highest responsibility
  • member - Active participant
  • consultant - Provides input when requested
  • support - Non-clinical support (case manager, etc.)

is_primary Flag

One participant can be marked as is_primary=True. This designates them as the lead care provider - the person to contact first about this patient.

Notification on Join

When a participant is added, an activity event notifies them. They now know they're part of this patient's care team and should receive relevant clinical updates.

The Notification Connection

Care Team Targeting

The care team is crucial for notification targeting. When something clinically significant happens to a patient, who should be notified?

The answer is often: the care team.

When a lab result arrives, NotificationRulesService.get_users_to_notify() queries the patient's active care team. All active members receive the notification (subject to their preferences).

Targeted Care

This is more precise than "notify everyone in the organization". Only the people actively involved in this patient's care receive updates. This reduces notification fatigue while ensuring relevant information reaches the right people.

Care Team Status Lifecycle

Status Progression

Teams move through statuses:

  • proposed - Team is being assembled
  • active - Team is functioning
  • suspended - Temporarily paused
  • inactive - No longer active
  • entered-in-error - Created by mistake

Practical Meaning

  • proposed teams exist but haven't started coordinating yet
  • active teams are the ones that receive notifications
  • suspended might happen during a patient's hospital stay when different teams take over
  • inactive is the normal end state when care concludes

Querying Care Teams

By Patient

The most common query: "Who is on this patient's care team?"

list_care_teams() with a patient filter returns all teams for a patient. Often there's just one active team, but patients with complex conditions might have multiple (one for cardiac care, one for diabetes management).

By Organization

Administrative views might show all care teams in the organization, perhaps filtered to show only active teams or teams needing attention.

By Participant

"Which teams am I on?" is a practitioner-centric query. The response shows all patients they're actively coordinating care for.

Participant Management

Updating Participants

A participant's role or dates may change without removing them. update_participant() allows modifying:

  • Role changes (member → lead)
  • Date adjustments
  • Primary designation changes

Removing Participants

When someone leaves the care team, remove_participant() handles the removal. This might:

  • Set an offboarding date (soft removal)
  • Remove the record entirely (hard removal)
  • Trigger an activity event noting the change

Automatic Removal

If a participant's offboarding_date passes, they're effectively no longer on the team. Queries for active participants filter by date.

Building Response Data

Rich Participant Data

When returning care team data, the service builds rich response objects. A participant entry includes:

  • Their user/practitioner details (name, email)
  • Their role on this team
  • Their dates of participation
  • Whether they're the primary contact

Practitioner Lookup

If the participant is a practitioner, their specialty, contact info, and photo are included. This helps teammates understand who's involved and how to reach them.

Integration Points

From Patient

The patient record has a care_teams relationship. When viewing a patient, you can see their active care teams and who's involved.

From Encounters

Encounters might reference care team context. During a care conference encounter, the attending members might be drawn from the care team roster.

To Notifications

As discussed, care teams are the primary targeting mechanism for clinical notifications. Changes to patient data notify the care team.

To ACL

Care team membership can influence access control. If ACL is configured, being on a patient's care team might grant access to that patient's records.

Activity Event Integration

Events for Team Changes

All significant care team operations trigger events:

  • CARE_TEAM_CREATED - New team formed
  • CARE_TEAM_UPDATED - Team details changed
  • CARE_TEAM_MEMBER_ADDED - Participant joined
  • CARE_TEAM_MEMBER_REMOVED - Participant left

Event Context

Events include the patient_id so they appear in the patient's activity timeline. They also include the care_team_id as the resource_id for navigation.

Key Takeaways

  1. Care teams coordinate care - Multiple providers, one patient

  2. FHIR-aligned structure - Interoperable with healthcare standards

  3. Participants have roles - Lead, member, consultant, support

  4. Primary designation - One person is the go-to contact

  5. Status lifecycle - Teams move from proposed to active to inactive

  6. Notification targeting - Care team receives clinical updates

  7. Rich participant data - Responses include full practitioner details

Next: Read about the Custom Forms Domain to understand dynamic data capture