# **TUTORHUB**

**FRONTEND GUIDE FOR AI CODING AGENTS - PART 13 - Messaging Service Realtime Hubs**

This document is a part of a REST API guide for the tutorhub project.
It is designed for AI agents that will generate frontend code to consume the project's backend.

This document provides the **Realtime Hub** integration guide for the **Messaging** service.
Realtime Hubs use **Socket.IO** for bidirectional communication between clients and the server, enabling features like chat rooms, live collaboration, game lobbies, and dashboards.

## Connection Setup

### Service URLs

The Socket.IO server runs on the same host as the REST API for the **messaging** service:

* **Preview:** `https://tutorhub.prw.mindbricks.com/messaging-api`
* **Staging:** `https://tutorhub-stage.mindbricks.co/messaging-api`
* **Production:** `https://tutorhub.mindbricks.co/messaging-api`

### Authentication

Every Socket.IO connection **must** include the user's access token and the correct `path` for the reverse proxy:

```js
import { io } from "socket.io-client";

const socket = io("{baseUrl}/hub/{hubName}", {
  path: "/messaging-api/socket.io/",  // HTTP transport path (reverse proxy)
  auth: { token: accessToken },           // Bearer token from login
  transports: ["websocket", "polling"],    // prefer websocket
});
```

Where `{baseUrl}` is the service base URL (e.g., `https://tutorhub.mindbricks.co/messaging-api`).

**How Socket.IO works behind a reverse proxy:**
- The URL passed to `io()` is `{baseUrl}/hub/{hubName}` where `{baseUrl}` already includes the service prefix (e.g., `/messaging-api`). Socket.IO extracts the full path after the host as the **namespace** (`/messaging-api/hub/{hubName}`). Namespaces are logical channels negotiated inside the Socket.IO protocol — the reverse proxy does not affect them.
- The `path` option (`/messaging-api/socket.io/`) is the **HTTP endpoint** the browser sends for the Socket.IO handshake, polling, and WebSocket upgrade. The reverse proxy routes this to the correct service and strips the prefix, so the server internally matches on the default `/socket.io/` path.

The server validates the token and resolves the user session before allowing any interaction. If the token is invalid or missing, the connection is rejected with an `"Authentication required"` or `"Invalid token"` error.


### Connection Lifecycle

```
connect  →  authenticate  →  join rooms  →  send/receive  →  leave rooms  →  disconnect
```

Listen for connection events:

```js
socket.on("connect", () => {
  console.log("Connected to hub", socket.id);
});

socket.on("connect_error", (err) => {
  console.error("Connection failed:", err.message);
  // Handle re-auth if token expired
});

socket.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);
});
```

## Protocol Reference

All hub events use the `hub:` prefix. Below is the complete protocol that applies to every hub in this service.

### Room Management

| Event | Direction | Payload | Description |
|-------|-----------|---------|-------------|
| `hub:join` | Client → Server | `{ roomId, meta? }` | Join a room. `meta` is optional user metadata broadcast to others. |
| `hub:joined` | Server → Client | `{ roomId, hubRole, userInfo }` | Confirmation that the client successfully joined. `userInfo` contains `{ fullname, avatar }`. |
| `hub:leave` | Client → Server | `{ roomId }` | Leave a room. |
| `hub:error` | Server → Client | `{ roomId?, error }` | Error response for any failed operation. |
| `hub:presence` | Server → Room | `{ event, roomId, user }` | Broadcast when a user joins or leaves. `event` is `"joined"` or `"left"`. `user` includes `{ id, fullname, avatar, hubRole }`. |

**Join a room:**

```js
socket.emit("hub:join", { roomId: "room-abc-123" });

socket.on("hub:joined", ({ roomId, hubRole, userInfo }) => {
  console.log("Joined room", roomId, "as", hubRole);
  // userInfo = { fullname: "John Doe", avatar: "https://..." }
});

socket.on("hub:presence", ({ event, roomId, user }) => {
  // user = { id, fullname, avatar, hubRole }
  if (event === "joined") showUserJoined(roomId, user);
  if (event === "left") showUserLeft(roomId, user);
});

socket.on("hub:error", ({ error }) => {
  console.error("Error:", error);
});
```

### Sending Messages

| Event | Direction | Payload |
|-------|-----------|---------|
| `hub:send` | Client → Server | `{ roomId, messageType, content, replyTo?, forwarded? }` |
| `hub:messageArrived` | Server → Room | `{ roomId, sender, message }` — `sender` includes `{ id, fullname, avatar }` |

**Send a message:**

```js
socket.emit("hub:send", {
  roomId: "room-abc-123",
  messageType: "text",
  content: { body: "Hello everyone!" }
});
```

**Receive messages:**

```js
socket.on("hub:messageArrived", ({ roomId, sender, message }) => {
  // sender = { id, fullname, avatar }
  // message = { id, messageType, content, timestamp, senderName, senderAvatar, ... }
  addMessageToUI(roomId, sender, message);
});
```

### History

When joining a room (if history is enabled), the server **automatically** sends the most recent messages right after the `hub:joined` event. Each message in the history array includes `senderName` and `senderAvatar` fields, so the frontend can render user display names and avatars without additional lookups.

| Event | Direction | Payload |
|-------|-----------|---------|
| `hub:history` | Server → Client | `{ roomId, messages[] }` |

**Automatic history on join:**

```js
socket.on("hub:history", ({ roomId, messages }) => {
  // messages are ordered newest-first, each has: id, roomId, senderId,
  // senderName, senderAvatar, messageType, content, timestamp, status
  renderMessageHistory(roomId, messages);
});
```

**Paginated history via REST (for "load more" / scroll-up):**

For older messages beyond the initial batch, use the REST endpoint:

```
GET /{hubKebabName}/{roomId}/messages?limit=50&offset=50
Authorization: Bearer {accessToken}
```

Response: `{ data: Message[], pagination: { total: number } }`

Each message in the REST response also contains `senderName` and `senderAvatar`.

### Custom Events

| Event | Direction | Payload |
|-------|-----------|---------|
| `hub:event` | Client → Server | `{ roomId, event, data }` |
| `hub:{eventName}` | Server → Room | `{ roomId, userId, ...data }` |

```js
// Emit a custom event
socket.emit("hub:event", {
  roomId: "room-abc-123",
  event: "customAction",
  data: { key: "value" }
});

// Listen for custom events
socket.on("hub:customAction", ({ roomId, userId, ...data }) => {
  handleCustomEvent(roomId, userId, data);
});
```

---

## Hub Definitions


## Hub: `chat`

**Namespace:** `/messaging-api/hub/chat`
**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).

### Connection

```js
const chatSocket = io("{baseUrl}/messaging-api/hub/chat", {
  path: "/messaging-api/socket.io/",
  auth: { token: accessToken },
  transports: ["websocket", "polling"]
});
```

### Room Settings

| Setting | Value |
|---------|-------|
| Room DataObject | `conversation` |
| Room Eligibility | `conversation.status == 'active'` |
| Absolute Roles (bypass auth) | `superAdmin` |

**Authorization Sources** (checked in order, first match wins):

| # | Name | Source Object | User Field | Room Field | Hub Role | Condition |
|---|------|-----------|------------|------------|----------|-----------|
| 1 | `participantACheck` | `conversation` | `participantA` | `id` | `member` | — |
| 2 | `participantBAdminStudent` | `conversation` | `participantB` | `id` | `viewer` | conversation.conversationType == 'adminStudent' |
| 3 | `participantBCheck` | `conversation` | `participantB` | `id` | `member` | conversation.conversationType != 'adminStudent' |


### Hub Roles

| Role | Read | Send | Allowed Types | Moderated | Moderate | Delete Any | Manage Room |
|------|------|------|---------------|-----------|----------|------------|-------------|
| `member` | Yes | Yes | all | No | No | No | No |
| `viewer` | Yes | No | all | No | No | No | No |

Users with `absoluteRoles` get a built-in **system** role with all permissions.

**Room Eligibility Check:**
Before joining, you can check if a room supports real-time features:

```
GET /chat/{roomId}/eligible
```

Response: `{ "success": true, "eligible": true/false }`

Use this to conditionally show/hide the chat UI.

### Message Types

Messages are stored in the **`chatMessage`** DataObject with the following structure:

| Field | Type | Description |
|-------|------|-------------|
| `id` | ID | Primary key |
| `roomId` | ID | Reference to the room |
| `senderId` | ID | Reference to the sending user |
| `senderName` | String | Display name of the sender (denormalized at send time) |
| `senderAvatar` | String | Avatar URL of the sender (denormalized at send time) |
| `messageType` | Enum | One of: `text`, `image`, `document`, `system`, `warning` |
| `content` | JSON | Type-specific payload (see below) |
| `timestamp` | DateTime | Message creation time |
| `replyTo` | JSON | Reply thread reference `{ id, preview }` |

#### Built-in Message Types

Each message type requires specific fields in the `content` object:

**`text`**

| Field | Type | Required |
|-------|------|----------|
| `body` | Text | Yes |

```js
socket.emit("hub:send", {
  roomId,
  messageType: "text",
  content: { body: "..." }
});
```

**`image`**

| Field | Type | Required |
|-------|------|----------|
| `mediaUrl` | String | Yes |
| `thumbnail` | String | No |
| `caption` | String | No |
| `width` | Integer | No |
| `height` | Integer | No |

```js
socket.emit("hub:send", {
  roomId,
  messageType: "image",
  content: { mediaUrl: "..." }
});
```

**`document`**

| Field | Type | Required |
|-------|------|----------|
| `mediaUrl` | String | Yes |
| `fileName` | String | Yes |
| `fileSize` | Integer | No |
| `mimeType` | String | No |

```js
socket.emit("hub:send", {
  roomId,
  messageType: "document",
  content: { mediaUrl: "...", fileName: "..." }
});
```

**`system`**

| Field | Type | Required |
|-------|------|----------|
| `systemAction` | String | Yes |
| `systemData` | JSON | No |

```js
socket.emit("hub:send", {
  roomId,
  messageType: "system",
  content: { systemAction: "..." }
});
```

#### Custom Message Types

**`warning`** — Admin warning message sent as part of moderation actions. Rendered with amber/yellow alert styling in the frontend.

| Field | Type | Required |
|-------|------|----------|
| `body` |  | Yes |
| `resolutionType` |  | No |
| `complaintId` |  | No |
| `severity` |  | Yes |

```js
socket.emit("hub:send", {
  roomId,
  messageType: "warning",
  content: { body: "...", severity: "..." }
});
```

### Cross-cutting Features

**Reply to messages:** Include `replyTo` in the send payload:

```js
socket.emit("hub:send", {
  roomId,
  messageType: "text",
  content: { body: "I agree!" },
  replyTo: originalMessageId
});
```




### Standard Events

| Event | Client Emits | Server Broadcasts |
|-------|-------------|-------------------|
| Typing | `hub:event` with `event: "typing"` | `hub:typing` `{ roomId, userId }` |
| Stop Typing | `hub:event` with `event: "stopTyping"` | `hub:stopTyping` `{ roomId, userId }` |
| Read Receipt | `hub:event` with `event: "messageRead"` | `hub:messageRead` `{ roomId, userId, lastReadTimestamp }` |
| Presence Online | _(automatic on connect)_ | `hub:online` `{ roomId, userId }` |
| Presence Offline | _(automatic on disconnect)_ | `hub:offline` `{ roomId, userId }` |

**Example — Typing indicator:**

```js
// Start typing
socket.emit("hub:event", { roomId, event: "typing" });

// Stop typing (call after a debounce timeout)
socket.emit("hub:event", { roomId, event: "stopTyping" });

// Listen for others typing
socket.on("hub:typing", ({ roomId, userId }) => {
  showTypingIndicator(roomId, userId);
});
socket.on("hub:stopTyping", ({ roomId, userId }) => {
  hideTypingIndicator(roomId, userId);
});
```

**Example — Read receipts:**

```js
// Mark messages as read
socket.emit("hub:event", {
  roomId,
  event: "messageRead",
  data: { lastReadTimestamp: new Date().toISOString() }
});

// Listen for read receipts
socket.on("hub:messageRead", ({ roomId, userId, lastReadTimestamp }) => {
  updateReadStatus(roomId, userId, lastReadTimestamp);
});
```



### Moderation Commands

Users with `canModerate` permission can block, silence, and manage messages:

**Block/Unblock a user:**

```js
socket.emit("hub:block", { roomId, userId: targetUserId, reason: "Spam", duration: 3600 });
socket.emit("hub:unblock", { roomId, userId: targetUserId });
```

**Silence/Unsilence a user:**

```js
socket.emit("hub:silence", { roomId, userId: targetUserId, reason: "Off-topic", duration: 600 });
socket.emit("hub:unsilence", { roomId, userId: targetUserId });
```

Duration is in seconds. `0` or omitted = permanent.

**Listen for moderation actions on your user:**

```js
socket.on("hub:blocked", ({ roomId, reason }) => {
  // You have been blocked — leave UI, show message
});
socket.on("hub:unblocked", ({ roomId }) => {
  // Block lifted — you may rejoin the room
});
socket.on("hub:silenced", ({ roomId, reason }) => {
  // You have been silenced — disable send button
});
socket.on("hub:unsilenced", ({ roomId }) => {
  // Silence lifted — re-enable send button
});
```



### REST API Endpoints

In addition to Socket.IO, the hub exposes REST endpoints for message history and management:

**Get message history:**

```
GET /chat/{roomId}/messages?limit=50&offset=0
```

Response:
```json
{
  "success": true,
  "data": [ /* message objects */ ],
  "pagination": { "limit": 50, "offset": 0, "total": 120 }
}
```

**Send a message via REST:**

```
POST /chat/{roomId}/messages
Content-Type: application/json
Authorization: Bearer {accessToken}

{
  "data": { "body": "Hello from REST" },
  "replyTo": null
}
```

Messages sent via REST are also broadcast to all connected Socket.IO clients in the room.

**Delete a message:**

```
DELETE /chat/{roomId}/messages/{messageId}
Authorization: Bearer {accessToken}
```

### Guardrails

| Limit | 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 |
| History on join | Last 50 messages |


## Frontend Integration Checklist

1. **Install socket.io-client:** `npm install socket.io-client`
2. **Create a connection manager** that handles connect/disconnect/reconnect with token refresh.
3. **Join rooms** after connection. Listen for `hub:joined` before sending messages. The `hub:joined` event includes the user's `hubRole` and `userInfo` (fullname, avatar).
4. **Render chat history** from the `hub:history` event that arrives automatically after joining. Each message includes `senderName` and `senderAvatar` for display.
5. **Handle `hub:error`** globally for all error responses.
6. **Use sender info** from `hub:messageArrived` events — the `sender` object includes `{ id, fullname, avatar }`. For history messages, use the stored `senderName` and `senderAvatar` fields.
7. **Parse `messageType`** to render different message bubbles (text, image, video, etc.).
8. **Use REST endpoints** for paginated history when scrolling up in a conversation (`GET /{hubKebabName}/{roomId}/messages?limit=50&offset=50`).
9. **Debounce typing indicators** — emit `typing` on keypress, `stopTyping` after 2–3 seconds of inactivity.
10. **Track read receipts** per room to show unread counts and read status.
11. **Handle presence** to show online/offline status. The `hub:presence` event includes `user.fullname` and `user.avatar` for display.
12. **Reconnect gracefully** — re-join rooms and fetch missed messages via REST on reconnect.

## Example: Full Chat Integration

```js
import { io } from "socket.io-client";

class ChatHub {
  constructor(baseUrl, token) {
    this.socket = io(`${baseUrl}/messaging-api/hub/chat`, {
      path: "/messaging-api/socket.io/",
      auth: { token },
      transports: ["websocket", "polling"]
    });

    this.rooms = new Map();
    this._setupListeners();
  }

  _setupListeners() {
    this.socket.on("hub:joined", ({ roomId, hubRole, userInfo }) => {
      this.rooms.set(roomId, { joined: true, hubRole, userInfo, messages: [], members: new Map() });
    });

    this.socket.on("hub:history", ({ roomId, messages }) => {
      const room = this.rooms.get(roomId);
      if (room) room.messages = messages;
      // Each message has senderName and senderAvatar for display
    });

    this.socket.on("hub:presence", ({ event, roomId, user }) => {
      const room = this.rooms.get(roomId);
      if (!room) return;
      if (event === "joined") {
        room.members.set(user.id, { fullname: user.fullname, avatar: user.avatar, hubRole: user.hubRole });
      } else if (event === "left") {
        room.members.delete(user.id);
      }
    });

    this.socket.on("hub:messageArrived", ({ roomId, sender, message }) => {
      // sender = { id, fullname, avatar }
      const room = this.rooms.get(roomId);
      if (room) room.messages.push(message);
      this.onNewMessage?.(roomId, sender, message);
    });

    this.socket.on("hub:error", ({ error }) => {
      console.error("[ChatHub]", error);
    });

    this.socket.on("hub:typing", ({ roomId, userId }) => {
      this.onTyping?.(roomId, userId, true);
    });
    this.socket.on("hub:stopTyping", ({ roomId, userId }) => {
      this.onTyping?.(roomId, userId, false);
    });

    this.socket.on("hub:online", ({ roomId, userId }) => {
      this.onPresence?.(userId, "online");
    });
    this.socket.on("hub:offline", ({ roomId, userId }) => {
      this.onPresence?.(userId, "offline");
    });
  }

  joinRoom(roomId) {
    this.socket.emit("hub:join", { roomId });
  }

  leaveRoom(roomId) {
    this.socket.emit("hub:leave", { roomId });
    this.rooms.delete(roomId);
  }

  sendMessage(roomId, messageType, content, options = {}) {
    this.socket.emit("hub:send", {
      roomId,
      messageType,
      content,
      ...options
    });
  }

  sendTyping(roomId) {
    this.socket.emit("hub:event", { roomId, event: "typing" });
  }

  sendStopTyping(roomId) {
    this.socket.emit("hub:event", { roomId, event: "stopTyping" });
  }

  disconnect() {
    this.socket.disconnect();
  }
}
```

**After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.**