Frame Gateway
The Frame Gateway is the public edge for frame state reads and live room updates. It exposes HTTP and Socket.IO to frame clients while the backend retains authorization, state evaluation, domain writes, and persistence.
Unlike the queue workers, the Frame Gateway also listens for internal NestJS TCP events from the backend.
Public HTTP Endpoint
| Method | Path | Function |
|---|---|---|
GET | /v1/frame/organization/:organizationId/room-state/:campaignId/data | Return the initial evaluated frame state |
The optional room query parameter selects a room slug. Browser cookies are forwarded to the backend for authorization. Responses use Cache-Control: no-store.
Socket.IO Endpoint
| Setting | Value |
|---|---|
| Namespace | /v1/frame |
| Transports | HTTP polling and WebSocket |
| Default public port | 3334 |
| Direction | Event | Function |
|---|---|---|
| Client to gateway | frame:join | Authorize and join one organization, campaign, and room |
| Gateway to client | frame:state | Deliver the current or newly published state snapshot |
| Client to gateway | frame:state:update | Submit an authenticated live-control state patch |
Internal TCP Endpoints
The gateway connects to the backend TCP receiver on port 3103 by default and listens for backend publications on port 3102 by default.
| Pattern | Direction | Function |
|---|---|---|
frame.gateway.state.get | Gateway to backend | Resolve the initial HTTP state request |
frame.gateway.join | Gateway to backend | Authorize a socket subscription and return current state |
frame.gateway.update | Gateway to backend | Validate and apply a live-control update |
frame.gateway.publish | Backend to gateway | Broadcast an evaluated state snapshot to matching clients |
Functionality
- Keeps public Socket.IO connections outside the main backend process.
- Uses the backend for every authorization and domain decision.
- Maps subscriptions to organization, campaign, and room-specific Socket.IO rooms.
- Replays current state after an accepted join.
- Broadcasts backend publications only to clients in the matching room.
- Supports deployments behind a proxy path through
PROXYPATH_PREFIX.
Local Start
Start the backend TCP receiver first, then run:
pnpm frame-gateway:devUse packages/frame-gateway/.env.example as the local environment template. The default HTTP URL is http://localhost:3334.