Messaging System

Architecture

The system uses CareTeam-based messaging rather than 1:1 practitioner-patient messaging:

Patient ──► CarePlan ──► CareTeam ──► Practitioners (multiple)
                              │
                              ▼
                    Message Room (real-time)

Why CareTeam-Based?

• A patient may have multiple providers (GP, specialist, nurse)
• All team members should see the same conversation
• Ensures continuity of care even when providers change
• Supports role-based participation (primary physician, nurse, etc.)

Room Identification

Each room is identified by:

careteam:{care_team_id}:patient:{patient_id}

Example: careteam:team-001:patient:ZCT_patient_001

Flow: Staff Sending a Message

1. Staff opens patient's profile
2. System finds CareTeams where staff is a participant AND patient is the subject
3. Staff selects room (or default team is used)
4. Message is sent with sender_resource_id
5. All team members + patient see the message in real-time

Flow: Patient Sending a Message

1. Patient opens conversations list
2. System shows all rooms from patient's CareTeams
3. Patient sends message
4. All CareTeam practitioners receive it in real-time

Unread Tracking

• Each message read status is tracked per-user in communication.message_read_status
• Unread counts are returned with conversation listings
• Mark-read updates the status for the specific user

Real-Time Delivery

Uses Supabase Realtime subscriptions:

supabase
  .channel('messages')
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'communication',
    table: 'messages',
    filter: `room_id=eq.${roomId}`
  }, (payload) => {
    // New message received
  })
  .subscribe();

Message Types

Sender Identity

The sender_resource_id field accepts both:

• FHIR resource_id (e.g., ZCT_doctor_001)
• Internal UUID (e.g., 7a2898cd-d088-...)

This dual-format support is needed because the staff GUI sends UUIDs while the token contains FHIR resource_ids.

API Reference

See Communication API for full endpoint documentation.