Realtime Hub Design Specification - chat
This document provides a detailed architectural overview of the chat realtime hub within the messaging service. It covers the hub’s room management, message handling, role-based authorization, event system, and server-side logic.
Hub Overview
Description: Real-time chat hub for TutorHub. Supports three channel types: studentTutor (bidirectional enrolled chat), adminStudent (one-way admin warnings to students), adminTutor (bidirectional admin-tutor communication). Authorization is role-aware: students in adminStudent rooms get viewer role (read-only).
- Socket.IO Namespace:
/hub/chat - Room DataObject:
conversation
Room Settings
Rooms are backed by the conversation DataObject. Each record in this object represents a room that users can join.
Room Eligibility
Before authorization checks, the following condition is evaluated. If it returns false, nobody can join the room:
conversation.status == 'active'
Authorization Flow
The hub uses a layered authorization flow to determine each user’s role when joining a room:
-
Absolute Roles: Users with roles
superAdminbypass all checks and receive thesystemhub role with full permissions. -
Auth Sources: The following DataObject-based authorization sources are checked in order. The first match determines the user’s hub role:
- participantACheck
- participantBAdminStudent
- participantBCheck
Hub Roles
| Role | Read | Send | Moderate | Delete Any | Manage Room | Moderated |
|---|---|---|---|---|---|---|
member |
Yes | Yes | No | No | No | No |
viewer |
Yes | No | No | No | No | No |
Message Settings
- Message DataObject:
chatMessage
Built-in Message Types
The following message types are supported:
textimagedocumentsystem
Cross-Cutting Features
- Reply Threading: Enabled — messages can reference a parent message via
replyTo - Reactions: Disabled
- Forwarded Flag: Disabled
Custom Message Types
- warning: Admin warning message sent as part of moderation actions. Rendered with amber/yellow alert styling in the frontend.
Fields:
[{"name":"body","fieldType":"Text","required":true,"description":"The warning message content"},{"name":"resolutionType","fieldType":"String","required":false,"description":"The moderation resolution type: warn, requireEdit, removeCourse, suspend, ban"},{"name":"complaintId","fieldType":"ID","required":false,"description":"Reference to the original complaint/issue ID"},{"name":"severity","fieldType":"Enum","required":true,"description":"Warning severity level","enumValues":"info,warning,critical","defaultValue":"warning"}]
Event Settings
Standard Events
| Event | Enabled | Type |
|---|---|---|
| Typing Indicator | Yes | Ephemeral |
| Recording Indicator | No | Ephemeral |
| Read Receipts | Yes | Persisted |
| Delivery Receipts | No | Persisted |
| Presence | Yes | Ephemeral |
Auto-Bridged DataObject Events
Auto-bridging of DataObject CRUD events is disabled for this hub.
History Settings
Guardrails
| Setting | Value |
|---|---|
| Max Users Per Room | 10 |
| Max Rooms Per User | 100 |
| Message Rate Limit | 30 msg/min |
| Max Message Size | 65536 bytes |
| Connection Timeout | 300000 ms |
| Auth Cache TTL | 300 seconds |
| Global Moderation | No |
| Default Silenced | No |
Server-Side Logic
This document was generated from the realtime hub configuration and should be kept in sync with design changes.