# Realtime Hub Design Specification - `lobbyChatHub`

This document provides a detailed architectural overview of the `lobbyChatHub` realtime hub within the `lobbyChat` service. It covers the hub's room management, message handling, role-based authorization, event system, and server-side logic.

## Hub Overview

**Description:** Public lobby chat hub. A single shared room where all authenticated users (guests and registered) can chat in real-time. Messages have 24-hour retention. Supports moderation: report, mute, and admin removal.

- **Socket.IO Namespace:** `/hub/lobbyChatHub`
- **Room DataObject:** `lobbyRoom`

## Room Settings


Rooms are backed by the `lobbyRoom` DataObject. Each record in this object represents a room that users can join.




### 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 `administrator` 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. **allowAllAuthenticated**






## Hub Roles

| Role | Read | Send | Moderate | Delete Any | Manage Room | Moderated |
|------|------|------|----------|------------|-------------|-----------|
| `lobbyUser` | Yes | Yes | No | No | No | No |
| `moderator` | Yes | Yes | Yes | Yes | No | No |


- **lobbyUser** is restricted to message types: `text`



## Message Settings


- **Message DataObject:** `lobbyChatHubMessage`


### Built-in Message Types
The following message types are supported:

- `text`
- `system`



### Cross-Cutting Features
- **Reply Threading:** Disabled
- **Reactions:** Enabled — emoji reactions supported on all message types
- **Forwarded Flag:** Disabled




## Event Settings


### Standard Events
| Event | Enabled | Type |
|-------|---------|------|
| Typing Indicator | Yes | Ephemeral |
| Recording Indicator | No | Ephemeral |
| Read Receipts | No | Persisted |
| Delivery Receipts | No | Persisted |
| Presence | Yes | Ephemeral |

### Auto-Bridged DataObject Events
CRUD events from the room, membership, and message DataObjects are automatically bridged via Kafka and broadcast to connected clients. This includes events like `memberJoined`, `messageEdited`, `roomUpdated`, etc.


### Custom Events
- **userMuted**
  - Direction: `serverToRoom`
  - Ephemeral: Yes
  - Broadcast when a user is muted in the lobby by an admin.
- **messageModerated**
  - Direction: `serverToRoom`
  - Ephemeral: Yes
  - Broadcast when a message is removed by admin moderation, so all users can hide it.







## History Settings




## Guardrails

| Setting | Value |
|---------|-------|
| Max Users Per Room | 1000 |
| Max Rooms Per User | 3 |
| Message Rate Limit | 20 msg/min |
| Max Message Size | 4096 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.*