Communication Service — Service Overview
Status: populated
Owner: TBD
Last updated: 2026-04-17
Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The communication-service is the unified digital communication backbone of the Ghasi-eHealth platform. It owns three tightly-related capabilities behind a single bounded context:
- Secure messaging between care-team members and, when licensed, between providers and patients.
- Outbound notification orchestration across push (FCM/APNs/WebPush), SMS (via Ghasi-SMS-Gateway and alternates), and email (SES / SendGrid / SMTP).
- Virtual session lifecycle management (join-token issuance, waiting-room, admission, fallback-to-messaging continuity) for telehealth encounters.
This consolidates the legacy messaging, notifications-platform, and virtual-care modules into one service per ADR-0047.
2. Bounded Context
Digital Communication — classified as Supporting (important but not a core domain differentiator). The capability is kept in-house because every clinical workflow (results, orders, scheduling, critical alerts) depends on PHI-safe delivery semantics that no SaaS notification vendor enforces by default.
3. Responsibilities
| Area | What communication-service Owns |
|---|
| Messaging threads | Thread lifecycle, participants, messages, read receipts, escalation |
| Patient-linked messaging | Optional patient/encounter linkage, chart-policy-filtered visibility |
| Attachments | Upload intake, malware-scan hook, size/type limits, MIME allowlists |
| Retention / legal hold | Per-tenant message retention policy, legal hold flags |
| Notification orchestration | Category → channel policy → template → provider dispatch |
| Provider adapters | Ports for SmsProvider, PushNotificationProvider, EmailProvider |
| Dispatch log | Audit-friendly per-channel outcome (no PHI in structured logs) |
| Virtual sessions | Session creation from scheduling events, join tokens, admit/remove |
| Fallback continuity | Automatic fallback messaging thread when virtual session fails |
| FHIR projection | Communication, CommunicationRequest, Encounter.class=VR |
4. Non-Responsibilities
| Area | Owner | Why Not Communication |
|---|
| Clinical notes content | patient-chart-service | Messaging is transport, not the chart of record |
| Scheduling | scheduling-service | Produces the appointment.* events that create virtual sessions |
| Identity / user auth | identity-service | Consumes JWTs; does not mint them |
| Consent records | patient-portal-service / tenant-service | Messaging enforces consent, does not store it |
| SMS delivery transport | Ghasi-SMS-Gateway (external) | Communication is the orchestrator; gateway is the carrier |
| AI summarization / tone | ai-gateway-service | All assistive AI routes through Kong /v1/ai/* |
5. Dependencies
5.1 Upstream (consumed)
| Dependency | Pattern | Purpose |
|---|
| identity-service | CF (JWT claims) | sub, tid, roles |
| scheduling-service | Event consumer | SCHEDULING.appointment.created / .cancelled / .reminder.sent |
| patient-portal-service | Event consumer | portal.notification.queued |
| laboratory-service / radiology-service | Event consumer | result.critical.flagged |
| Ghasi-SMS-Gateway | ACL (adapter) | Regional SMS delivery with DLR callbacks |
| FCM / APNs / WebPush | ACL (adapter) | Push delivery |
| SES / SendGrid / SMTP | ACL (adapter) | Email delivery |
| interop-service / fhir-gateway | Downstream | Creates Communication, reads Patient, Encounter |
| config-service | Pull | Tenant branding, templates, channel policy |
5.2 Downstream (produced events)
| Consumer | Consumes |
|---|
| audit-service | .dispatched metadata for accounting of disclosures |
| patient-chart-service | .message.sent when patient-linked to project into chart timeline |
| virtual-care UX | virtual_session.* realtime signals |
| billing-service | virtual_session.billing.chargeable |
6. Slice Involvement
| Slice | Scope | Milestone |
|---|
| S1 | Provider-to-provider messaging, basic email notifications, SMS via Ghasi-SMS-Gateway | M1 |
| S2 | Patient messaging (when portal licensed), push notifications, virtual session lifecycle | M2 |
| S3 | Advanced escalation policies, critical-result fan-out, fallback-to-messaging from virtual care | M3 |
| S4 | Digest bundling, bounce analytics, per-tenant channel SLOs | M4 |
7. Key Architectural Decisions
- One service, three capabilities. Messaging, notifications, and virtual sessions share the same tenancy model, auth surface, FHIR projection (
Communication), and outbox stream — keeping them in one service prevents four-way coordination.
- Ghasi-SMS-Gateway is an adapter, not a replacement. Regional rollouts in Afghanistan use Ghasi-SMS-Gateway; other deployments plug Twilio / Vonage without domain-layer changes.
- No PHI in push/SMS/email by default. Dispatch payloads carry opaque ids, deep links, and template keys.
BR-MSG-001 / BR-PORT-003.
- Canonical CloudEvents types.
ghasi.digital_communication.* is the canonical prefix; legacy ghasi.messaging.* and VIRTUAL_CARE.* subjects dual-publish during migration.
- Fallback continuity is first-class. A failed virtual session automatically spawns a secure messaging thread linking session id so care continues without manual re-wiring.
8. Architecture Diagram
9. Source reconciliation
Merged _sources/messaging/ (COM-MSG, deprecated) + _sources/digital-communication/ (COM-DCOM, canonical) per ADR-0047:
| Decision | Outcome |
|---|
| Canonical prefix | All new routes under /v1/communication/*; legacy /v1/digital-communication/* and /v1/messaging/* remain for migration |
| FR ID unification | FR-COMMS-MSG-*, FR-COMMS-NOTIF-*, FR-COMMS-VC-* adopted; legacy FR-MSG-*, FR-DCOM-* preserved in traceability column |
| Events | ghasi.digital_communication.* is canonical; ghasi.messaging.* and VIRTUAL_CARE.* dual-publish until M3 |
| Virtual-care scope | Kept inside communication-service; separate virtual-care-service is retired per ADR-0047 |