Skip to main content

Virtual Care Service — Event Schemas

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

1. Conventions​

ConventionValue
Event domainvirtual_care (per NAMING.md)
Event type formatvirtual_care.{aggregate}.{event}.v{N}
NATS subjectSame as event type
Stream nameVIRTUAL_CARE
Subjects patternvirtual_care.>
Sourceghasi/virtual-care-service
EnvelopeCloudEvents 1.0
PHI in eventsProhibited — only metadata (IDs, timestamps, status, counts); no session content, no clinical notes, no credentials

2. NATS JetStream Configuration​

SettingValue
Stream nameVIRTUAL_CARE
Subjectsvirtual_care.>
StorageFile
Replicas3 (production)
RetentionLimits — 7-day default
Max message size64 KB
Discard policyOld

3. Events Produced​

3.1 virtual_care.session.created.v1​

Trigger: Session created + room provisioned. Consumers: audit-service, scheduling-service.

{
  "specversion": "1.0",
  "type": "virtual_care.session.created.v1",
  "source": "ghasi/virtual-care-service",
  "id": "<uuid>",
  "time": "2026-04-20T09:55:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "appointmentId": "<uuid>",
    "videoBackend": "jitsi",
    "scheduledStart": "2026-04-20T10:00:00Z",
    "scheduledEnd": "2026-04-20T10:30:00Z"
  }
}

3.2 virtual_care.session.started.v1​

Trigger: First provider joins; session transitions to active. Consumers: audit-service, billing-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "initiatingProviderId": "<uuid>",
    "videoBackend": "jitsi"
  }
}

3.3 virtual_care.session.participant.joined.v1​

Trigger: Participant validates join token. Consumers: audit-service.

{
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "participantId": "vsp_01HX...",
    "userId": "<uuid>",
    "role": "patient",
    "participantStatus": "waiting"
  }
}

3.4 virtual_care.session.participant.admitted.v1​

Trigger: Provider admits patient from waiting room. Consumers: audit-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "participantId": "vsp_01HX...",
    "userId": "<uuid>",
    "role": "patient"
  }
}

3.5 virtual_care.session.participant.removed.v1​

Trigger: Provider removes a participant. Consumers: audit-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "participantId": "vsp_01HX...",
    "userId": "<uuid>",
    "removeReason": "provider_action"
  }
}

3.6 virtual_care.session.ended.v1​

Trigger: Session transitions to ended. Consumers: audit-service, scheduling-service, patient-chart-service (triggers Encounter creation via FHIR), billing-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "appointmentId": "<uuid>",
    "encounterId": "enc_01HX...",
    "videoBackend": "jitsi",
    "actualStart": "2026-04-20T10:02:00Z",
    "actualEnd": "2026-04-20T10:28:00Z",
    "durationSeconds": 1560,
    "participantCount": 2,
    "recordingRef": null
  }
}

3.7 virtual_care.session.cancelled.v1​

Trigger: Session cancelled before active. Consumers: audit-service, scheduling-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "appointmentId": "<uuid>",
    "reason": "Patient unable to connect"
  }
}

3.8 virtual_care.session.failed.v1​

Trigger: Grace reconnect expired; session transitions to failed. Consumers: audit-service, communication-service.

{
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "videoBackend": "jitsi",
    "failureReason": "WebRTC room unreachable after 60s grace period",
    "previousStatus": "active"
  }
}

3.9 virtual_care.session.fallback.initiated.v1​

Trigger: Async messaging fallback triggered. Consumers: communication-service (creates thread), audit-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "messagingThreadId": "thr_01HX..."
  }
}

3.10 virtual_care.config.updated.v1​

Trigger: Tenant config changed. Consumers: audit-service. Note: Never includes credentials.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "changedFields": ["brandingLogoUrl", "recordingEnabled"]
  }
}

3.11 virtual_care.billing.session_chargeable.v1​

Trigger: Session ended with Encounter ID. Consumers: billing-service.

{
  "data": {
    "tenantId": "<uuid>",
    "sessionId": "vsn_01HX...",
    "patientId": "<uuid>",
    "encounterId": "enc_01HX...",
    "appointmentId": "<uuid>",
    "durationSeconds": 1560,
    "videoBackend": "jitsi",
    "actualStart": "2026-04-20T10:02:00Z",
    "actualEnd": "2026-04-20T10:28:00Z"
  }
}

3.12 virtual_care.async_visit.submitted.v1​

Trigger: Store-and-forward async visit submitted. Consumers: audit-service, patient-chart-service.

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "sessionId": "avs_01HX...",
    "patientId": "<uuid>",
    "appointmentId": "<uuid>",
    "hasAttachments": true,
    "submittedAt": "2026-04-20T14:00:00Z"
  }
}

4. Events Consumed​

NATS SubjectSource ServiceHandling
scheduling.appointment.scheduled.v1scheduling-serviceAuto-create VirtualSession when serviceType=VR
scheduling.appointment.cancelled.v1scheduling-serviceCancel VirtualSession if scheduled or waiting