WebSocket Gateway for Real-Time Healthcare Platform

Business Challenge (Business Problem)

The healthcare platform needed a secure, reliable, and scalable real-time communication channel to connect over 500+ distributed healthcare units with the central ecosystem.

• Existing REST APIs handled transactional workflows but lacked low-latency bidirectional communication.

• Remote healthcare units required instant updates (appointments, registrations, payments) while ensuring compliance, security, and fault-tolerance.

Failures in request routing or delayed responses directly impacted patient experience and operational efficiency.

Vision & Strategy (High-Level Goal)

The strategy was to centralize real-time communication through a WebSocket Gateway that:

• Acts as a single entry point for all WebSocket traffic.

• Supports both API Gateway traffic (via API Bridge) and direct portal applications.

• Provides end-to-end reliability with authentication, monitoring, error-handling, and timeout management.

• Enables scalability to thousands of concurrent connections while maintaining observability.

Architecture Solution (Architecture Design)

High-Level Flow

1. Healthcare staff use the Portal Web App (browser) or backend APIs.

2. The API Gateway sends traffic to the WebSocket Gateway via the API Bridge.

3. The WebSocket Gateway securely routes traffic to the respective Healthcare Unit Systems.

4. Responses and updates flow back to the Portal or API Gateway in real time.

(Visualized in the Context Diagram)

Components Interactions

1. Connection Manager: Establishes & maintains WebSocket sessions with health units and portal clients.

2. Authentication Module: Validates JWT tokens and enforces secure access.

3. Routing Engine: Routes API and WebSocket traffic to the correct healthcare unit.

4. Message Handler: Parses incoming messages and ensures schema compliance.

5. Monitoring & Logging: Provides observability via logs, metrics, and error tracing.

(Visualized in the Container Diagram)

Detailed Flow (Component View)

1. Portal Web App connects directly to the Connection Manager → connection authenticated via Authentication Module.

2. API Gateway → API Bridge → forwards REST-translated requests into the Authentication Module.

3. Routing Engine → forwards traffic to the correct Healthcare Unit Services.

4. Healthcare Unit Services → responses flow back via the Message Handler.

5. Monitoring & Logging ensures system health, error handling, and near-zero failure rate.

(Visualized in the Component Diagram)

Architectural Decisions Records (ADRs)

• Node.js for WebSocket Gateway: Chosen for non-blocking I/O and event-driven architecture.

• JWT-based Authentication: Ensures secure client validation across distributed healthcare units.

• Centralized Connection Pool: Maintains active, heartbeat-validated WS connections for 500+ units.

• Timeout & Callback Registry: Implemented Map-based pending request tracking to guarantee responses or fail-fast with logged errors.

• Generalized JSON Schema: Standardized request/response schema for future-proof extensibility.

• Observability Stack: Logging with Winston + monitoring with PM2 for reliability and insights.

Key Achievements (Business Impact)

• Unified communication layer: Simplified integration for 500+ healthcare units through a single secure gateway.

• Improved reliability: Failures reduced to near-zero via timeout handling and monitoring.

• Enhanced scalability: Architecture supports thousands of concurrent real-time connections.

• Better troubleshooting: Centralized logging and metrics provided actionable insights during rollout.

• Future readiness: Designed for extensibility, supporting new event types and real-time workflows without redesign.