Realtime Hub Design Specification - gameHub

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

Hub Overview

Description: Real-time chess game hub. Each chessGame is a room where two players exchange moves, see board state, and receive game lifecycle events (draw offer, resign, timeout, save requests). Supports both guest and registered players.

• Socket.IO Namespace: /hub/gameHub
• Room DataObject: chessGame

Room Settings

Rooms are backed by the chessGame 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:

chessGame.status == 'active' || chessGame.status == 'pending' || chessGame.status == 'paused'

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.

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

   1. whitePlayer
   2. blackPlayer

Hub Roles

Role	Read	Send	Moderate	Delete Any	Manage Room	Moderated
player	Yes	Yes	No	No	No	No

Message Settings

Built-in Message Types

The following message types are supported:

• text
• system

Cross-Cutting Features

• Reply Threading: Disabled
• Reactions: Disabled
• Forwarded Flag: Disabled

Custom Message Types

• chessMove: App-specific message type Fields: []
• drawOffer: App-specific message type Fields: []
• drawAccepted: App-specific message type Fields: []
• drawDeclined: App-specific message type Fields: []
• resignation: App-specific message type Fields: []
• saveRequest: App-specific message type Fields: []
• saveAccepted: App-specific message type Fields: []
• saveDeclined: App-specific message type Fields: []
• resumeRequest: App-specific message type Fields: []
• resumeAccepted: App-specific message type Fields: []
• resumeDeclined: App-specific message type Fields: []

Event Settings

Standard Events

Event	Enabled	Type
Typing Indicator	No	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

• gameStateUpdate
  • Direction: serverToRoom
  • Ephemeral: Yes
  • Broadcast updated game state (status, result, timers) to both players when the game state changes server-side.
• clockTick
  • Direction: serverToRoom
  • Ephemeral: Yes
  • Server broadcasts remaining time for each player (for timed/blitz/rapid games).

History Settings

Guardrails

Setting	Value
Max Users Per Room	3
Max Rooms Per User	5
Message Rate Limit	120 msg/min
Max Message Size	16384 bytes
Connection Timeout	600000 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.