# 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:

```js
conversation.status == 'active'
```


### Authorization Flow

The hub uses a layered authorization flow to determine each user's role when joining a room:


1. **Absolute Roles:** Users with roles `superAdmin` bypass all checks and receive the `system` hub role with full permissions.







4. **Auth Sources:** The following DataObject-based authorization sources are checked in order. The first match determines the user's hub role:

   1. **participantACheck**
   2. **participantBAdminStudent**
   3. **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:

- `text`
- `image`
- `document`
- `system`



### 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.*