Teleconsultation (Video Sessions)

Video Session Lifecycle

  Create Session ──> Schedule Notifications ──> Reminders fire
        │                    │                       │
        ▼                    ▼                       ▼
  Ably: session_created   SlackJob: 'new'     TeleconsultationReminderJob
        │                                    (doctor_15min / patient_10min / at_time)
        ▼
  Patient joins ──> Doctor joins ──> Session active
        │                                 │
        ▼                                 ▼
  Ably: participant_joined          Ably: call_started
                                          │
                              ┌───────────┴───────────┐
                              ▼                       ▼
                       Complete session         Timeout (30min)
                              │                       │
                              ▼                       ▼
                    SlackJob: 'complete'     SlackJob: 'timed_out'
                    Ably: session_completed  Ably: session_timed_out

CREATE TABLE clinical.video_sessions (
  id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id           UUID NOT NULL REFERENCES identity.tenants(id),
  encounter_id        UUID NOT NULL REFERENCES clinical.encounters(id),
  provider            VARCHAR DEFAULT 'vonage',   -- vonage | twilio | agora
  provider_session_id VARCHAR,
  status              VARCHAR DEFAULT 'created',  -- created | active | completed | failed | timed_out
  started_at          TIMESTAMP,
  completed_at        TIMESTAMP,
  metadata            JSONB DEFAULT '{}',
  created_at          TIMESTAMP NOT NULL,
  updated_at          TIMESTAMP NOT NULL
);

-- Indexes
CREATE INDEX idx_vs_tenant ON clinical.video_sessions (tenant_id);
CREATE INDEX idx_vs_encounter ON clinical.video_sessions (encounter_id);
CREATE INDEX idx_vs_tenant_status ON clinical.video_sessions (tenant_id, status);
CREATE INDEX idx_vs_provider_session_id ON clinical.video_sessions (provider_session_id);

CREATE TABLE clinical.video_session_participants (
  id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id         UUID NOT NULL REFERENCES identity.tenants(id),
  video_session_id  UUID NOT NULL REFERENCES clinical.video_sessions(id),
  participant_type  VARCHAR NOT NULL,    -- practitioner | patient | family
  participant_id    UUID NOT NULL,
  role              VARCHAR DEFAULT 'participant',  -- host | participant | observer
  token             TEXT,
  token_expires_at  TIMESTAMP,
  joined_at         TIMESTAMP,
  left_at           TIMESTAMP,
  declined_at       TIMESTAMP,
  connection_id     VARCHAR,
  metadata          JSONB DEFAULT '{}',
  created_at        TIMESTAMP NOT NULL,
  updated_at        TIMESTAMP NOT NULL,
  UNIQUE (video_session_id, participant_type, participant_id)
);

-- Indexes
CREATE INDEX idx_vsp_tenant ON clinical.video_session_participants (tenant_id);
CREATE INDEX idx_vsp_session ON clinical.video_session_participants (video_session_id);

CREATE TABLE shared.notification_logs (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id       UUID,
  channel         VARCHAR NOT NULL,     -- sms | push | whatsapp | slack | email
  status          VARCHAR NOT NULL DEFAULT 'pending',  -- pending | sent | delivered | failed | bounced
  recipient       VARCHAR NOT NULL,
  content         TEXT,
  template_id     VARCHAR,
  provider        VARCHAR,              -- twilio | msg91 | sns | slack
  provider_id     VARCHAR,
  failure_reason  VARCHAR,
  metadata        JSONB DEFAULT '{}',
  created_at      TIMESTAMP NOT NULL,
  updated_at      TIMESTAMP NOT NULL
);

-- Indexes
CREATE INDEX idx_notif_logs_tenant ON shared.notification_logs (tenant_id);
CREATE INDEX idx_notif_logs_channel ON shared.notification_logs (channel);
CREATE INDEX idx_notif_logs_dedup ON shared.notification_logs (channel, recipient, created_at);
CREATE INDEX idx_notif_logs_created_at ON shared.notification_logs (created_at);

ALTER TABLE clinical.video_sessions ENABLE ROW LEVEL SECURITY;
ALTER TABLE clinical.video_sessions FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON clinical.video_sessions
  FOR ALL USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

# Key constants
VALID_PROVIDERS = ['vonage', 'twilio', 'agora']
VALID_STATUSES  = ['created', 'active', 'completed', 'failed', 'timed_out']

# Key constants
VALID_PARTICIPANT_TYPES = ['practitioner', 'patient', 'family']
VALID_ROLES             = ['host', 'participant', 'observer']

created ──> active ──> completed
   │           │
   │           └──> failed
   │
   └──> timed_out (30-min no-show)

# Valid types: 'new', 'delay', 'complete', 'timed_out', 'cancelled'
Clinical::SlackNotificationJob.set(wait: 5.seconds).perform_later(video_session.id, 'new')

# Valid types: 'doctor_15min', 'patient_10min', 'at_time'
Clinical::TeleconsultationReminderJob
  .set(wait_until: slot_time - 15.minutes)
  .perform_later(encounter.id, 'doctor_15min')

Clinical::VideoSessionTimeoutJob.set(wait: 30.minutes).perform_later(video_session.id)