Chat &
Realtime Alerts
The Realtime module powers instant communication across the hospital—secure chat between staff, live notifications for critical events, and real-time presence tracking so you always know who's available.
What is Realtime Communication?
The Realtime module provides two main capabilities: Chat (secure instant messaging between staff, including one-on-one and group conversations) and Notifications (system-generated alerts for events like new lab results, emergency cases, and billing updates). Both are delivered instantly via Socket.IO technology.
Chat features include text messaging, message replies, emoji reactions, typing indicators, read receipts, file sharing, message search, and conversation management (mute, hide). Notifications can be filtered by category and broadcast to specific roles or departments.
Why Does It Exist?
- → Speed of communication — In emergencies, waiting for a page or phone call wastes precious minutes
- → Secure messaging — Consumer apps lack hospital audit controls; HMIS chat is permission-gated, logged, and enterprise-wide (customer BAA and acceptable-use policy still required)
- → Audit trail — Clinical decisions communicated via chat are logged for medicolegal purposes
- → Reduced noise — Staff can mute non-urgent conversations and still receive critical alerts
How Chat Works
Start a Conversation
Users can start a direct chat with another staff member (one-on-one) or create a group conversation (e.g., "ER Team" or "Cardiology Department"). The system shows which colleagues are currently online (green dot) and available.
Send & Receive Messages
Messages appear instantly in the recipient's chat window. Typing indicators show when someone is composing a reply. Read receipts show when the message has been seen. Emoji reactions can be added to any message.
Manage Conversations
Users can mute conversations (stop notifications but still receive messages), hide conversations (remove from view without deleting), and search through message history. Group admins can add or remove members.
Notifications & Alerts
The system can generate notifications for clinical events (new lab result, emergency case, bed assignment). Users can filter notifications by category, mark them as read, and configure which types they want to receive. Emergency alerts override mute settings.
Every Feature Explained
Direct & Group Chat
Send instant messages to individuals or groups.
Enables quick, secure communication without phone calls or insecure apps.
Start a direct chat by selecting a colleague. Create groups for teams or departments. All messages are encrypted in transit and stored securely.
Typing Indicators & Read Receipts
See when someone is typing and when they've read your message.
Provides conversational context. You know if someone is ignoring you vs. hasn't seen the message yet.
Typing status is broadcast via Socket.IO in real-time. Read receipts update when the recipient opens the conversation. Can be toggled off for privacy.
Message Reactions & Replies
React to messages with emojis or reply to specific messages in a thread.
Reduces clutter by allowing quick acknowledgment (thumbs up) without a separate message.
Click the reaction button on any message. Replies create an inline thread that keeps the conversation organized.
Notification Categories & Preferences
Choose which types of notifications you want to receive.
Different staff need different alerts. A doctor needs critical lab results; a receptionist needs appointment notifications.
Notification categories include: Emergency, Clinical, Billing, Administrative, System. Users toggle categories on/off. Emergency overrides ignore preferences.
Broadcast Messages
Send notifications to everyone in a role or department.
Useful for announcements (e.g., 'Code Blue in ICU') or department updates.
Broadcasts are sent via Socket.IO to all users who have the matching role or department permission. Recipients see the broadcast even if they've muted other notifications.
Module Live Updates
Campus-scoped Socket.IO rooms for admissions, emergency, OT, blood bank, ambulance, billing, housekeeping, and critical lab alerts.
Dashboards stay fresh without manual refresh; mine-scoped users never receive other campuses' operational or PHI-bearing events.
The API emits typed events to <code>module:branchId</code> rooms (plus a global room only for <code>branches:view:all</code>). Module dashboards invalidate Working-in React Query caches on these events; critical paths also create persisted <code>new_notification</code> rows.
Message Search & History
Search through past conversations and messages.
Critical information shared in chat (lab values, instructions) needs to be retrievable later.
Search indexes all messages in MongoDB. Results are scoped to conversations the user has access to. History is retained for audit purposes.
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| message_id | UUID | Unique identifier for each chat message. |
| sender_id | UUID | The staff member who sent the message. |
| room_id | UUID | The chat room (direct or group) this message belongs to. |
| message_type | Enum | Text, File, System, Reply, Reaction. |
| is_read | Boolean | Whether the recipient has seen the message. |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
chat:usechat:managenotifications:viewnotifications:broadcastSocket.IO Architecture
Persistent WebSocket connections deliver messages instantly. When multiple server instances run, Redis fan-out ensures messages reach all instances.
MongoDB Persistence
Chat messages and chat-based notifications are stored in MongoDB for scalability. PostgreSQL stores application-level notifications.
Dual notification stores (known limitation)
In-app alerts may exist in PostgreSQL (module events) and MongoDB (chat-adjacent delivery). There is no unified cross-store inbox yet, operators should treat this as an architectural constraint when auditing notification delivery or planning consolidation.
JWT Authentication
Socket connections are authenticated using the same JWT tokens as the REST API. This ensures only authorized staff can connect.