Skip to main content

ADR-0047: Unified Digital Communication service (messaging + virtual visits)

Status: Accepted
Date: 2026-04-09
Deciders: Platform architecture
Supersedes: Separate deployment boundaries for messaging and virtual-care as distinct bounded-context deployables.

Context​

The platform requires a single owner for all non–in-person mediated communication: secure messaging, outbound notifications, and synchronous virtual visits (telehealth). Operating two microservices (messaging, virtual-care) duplicated operational overhead, split client configuration, and blurred product boundaries for “one channel” retention and UI.

Decision​

  1. One deployable — digital-communication-service (apps/services/digital-communication) — consolidates former messaging and virtual-care NestJS applications into one process with subdomains (Messaging, VirtualVisits, Notifications).

  2. Retire standalone apps/services/messaging and apps/services/virtual-care: they are removed from the repository. The single deployable digital-communication exposes Kong routes under /v1/digital-communication/* (see specs/modules/digital-communication/API_DOCS.md).

  3. Database: Single PostgreSQL database per deployment (DATABASE_URL for digital-communication), containing both former messaging tables (message_threads, …) and virtual session tables (virtual_sessions, …). No cross-service DB calls.

  4. NATS: Event subjects for virtual sessions may keep legacy VIRTUAL_CARE.* names as aliases published alongside DIGITAL_COMMUNICATION.virtual_session.* during migration; consumers update to canonical names per specs/modules/digital-communication/EVENT_MODEL.md.

  5. Licensing (product): Externally, tenants may still purchase “Messaging” and “Virtual Care” capabilities. Internally, both map to entitlement checks on the same service (engage.messaging, engage.virtual_care module keys, or future engage.digital_communication with feature flags — product catalog may retain separate SKUs). The ADR does not mandate collapsing license keys; it mandates one codebase.

Consequences​

  • Positive: One container to scale, one set of secrets/env, unified audit story for threads + visits, simpler STT→APSO trigger ownership.
  • Negative: Larger binary; teams must use strict Nest module boundaries inside the monolith to avoid spaghetti.
  • Migration: Requires DB consolidation for environments that had split DBs, Kong route updates (/v1/digital-communication), and client path updates from legacy /v1/messaging / /v1/virtual-sessions where still referenced.

References​