WebSocket Architecture

WebSocket connections enable real-time, bidirectional communication between browser clients and the MATIH Platform. They are primarily used for streaming AI responses, live dashboard updates, and real-time notifications.

WebSocket Use Cases

Use Case	Endpoint	Data Direction	Protocol
AI response streaming	`/ws/ai/chat`	Server to client	WebSocket
Dashboard live refresh	`/ws/bi/dashboards/{id}`	Server to client	WebSocket
Notifications	`/ws/notifications`	Server to client	WebSocket
Collaborative editing	`/ws/collaboration/{id}`	Bidirectional	WebSocket

Connection Flow

Browser                   Kong Gateway              Backend Service
  |                           |                          |
  | HTTP Upgrade: websocket   |                          |
  | Authorization: Bearer JWT |                          |
  |-------------------------->|                          |
  |                           |                          |
  |         Validate JWT      |                          |
  |         Extract tenant_id |                          |
  |         Rate limit check  |                          |
  |                           |                          |
  |                           | Forward upgrade          |
  |                           |------------------------->|
  |                           |                          |
  |                           |          Accept upgrade  |
  |                           |          Establish WS    |
  |                           |<-------------------------|
  | 101 Switching Protocols   |                          |
  |<--------------------------|                          |
  |                           |                          |
  | WebSocket frames          |                          |
  |<========================================>            |

AI Streaming Architecture

The AI Service streams tokens through a Redis Pub/Sub bridge:

AI Service (Python/FastAPI)
  |
  | Generate tokens via LLM
  |
  v
Redis Pub/Sub
  | Channel: ai:stream:{sessionId}
  |
  v
WebSocket Bridge
  | Subscribe to session channel
  | Forward tokens as WebSocket frames
  |
  v
Browser
  | Receive tokens incrementally
  | Update UI in real-time

Message Format

{"type": "token", "data": {"token": "Revenue", "index": 0}}
{"type": "token", "data": {"token": " was", "index": 1}}
{"type": "token", "data": {"token": " $2.4M", "index": 2}}
{"type": "complete", "data": {"sql": "SELECT ...", "chartConfig": {...}}}
{"type": "error", "data": {"code": "QUERY_FAILED", "message": "..."}}

Authentication

WebSocket connections are authenticated at connection time:

Step	Action
1	Client sends JWT token in the initial HTTP upgrade request
2	Gateway validates JWT and extracts tenant context
3	Backend service verifies token and establishes session
4	All subsequent frames are authorized via the initial token
5	Token refresh requires reconnection

Connection Lifecycle

Event	Action
Connect	Authenticate, subscribe to relevant Redis channels
Message (client to server)	Process command (e.g., new chat message)
Message (server to client)	Forward event from Redis Pub/Sub
Heartbeat	Ping/pong every 30 seconds
Disconnect	Unsubscribe from channels, clean up session
Reconnect	Client auto-reconnects with exponential backoff

Redis Pub/Sub -- Backend real-time messaging
Agent Flow -- AI streaming response flow
Browser to Gateway -- Initial connection flow

Redis Pub/Sub CDC Patterns