Websockets & Real-time Updates

The OnChain Sage backend leverages WebSockets to facilitate real-time, bidirectional communication with the frontend. This is a core component for delivering timely data, such as trading signals and notifications, to the user dashboard, ensuring an interactive and responsive user experience. The implementation uses the @nestjs/websockets and @nestjs/platform-socket.io packages, built on top of socket.io.

The architecture defines two primary gateways, SignalGateway and WebsocketGateway, which are consolidated within a dedicated GatewayModule.

Sources: ARCHITECTURE.md, apps/backend/package.json:44-45, 48

Architecture and Module Integration

The WebSocket functionality is encapsulated within the GatewayModule. This module registers the SignalGateway and WebsocketGateway as providers, making them available for handling real-time client connections and events within the NestJS application.

Sources: apps/backend/src/gateways/gateway.module.ts:1-10

The diagram below illustrates the composition of the GatewayModule.

Gateways

SignalGateway

The SignalGateway is specifically designed to broadcast new trading signals to all connected clients. It manages the lifecycle of client connections and provides a method to push signal data.

Sources: apps/backend/src/gateways/signal.gateway.ts

Key Components & Lifecycle

• @WebSocketGateway: Decorator that marks the class as a WebSocket gateway, configured with CORS to allow all origins.
• @WebSocketServer: Injects the socket.io server instance.
• OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect: NestJS lifecycle hooks implemented to log server initialization and client connection/disconnection events.
• sendSignal(signal: any): A public method that emits a newSignal event to all connected clients, broadcasting the provided signal data.

The following sequence diagram shows the client connection and signal broadcast flow.

WebsocketGateway

The WebsocketGateway (note the filename typo websocket.getway.ts) provides more generic real-time communication functionalities, including broadcasting messages to all clients and sending targeted messages to specific users. It also manages a map of connected clients.

Sources: apps/backend/src/notification/websocket/websocket.getway.ts

Key Components & Methods

• @WebSocketGateway: Configured with CORS to allow connections from any origin.
• clients: Map<string, Socket>: A map to store connected clients, using the client ID as the key.
• handleConnection(client: Socket): Adds the new client to the clients map upon connection.
• handleDisconnect(client: Socket): Removes the client from the clients map upon disconnection.
• sendToUser(userId: string, event: string, data: any): Sends a message for a specific event with data to a single client identified by userId.
• broadcast(event: string, data: any): Broadcasts a message to all connected clients.

Sources: apps/backend/src/notification/websocket/websocket.getway.ts:19-58

The table below summarizes the public methods of the WebsocketGateway.

Sources: apps/backend/src/notification/websocket/websocket.getway.ts:50-58

The following flowchart shows the logic for sending a user-specific notification.

Summary

The WebSocket implementation in OnChain Sage provides a robust foundation for real-time features. The SignalGateway is specialized for broadcasting trading signals, while the WebsocketGateway offers general-purpose messaging capabilities, including targeted user notifications and global broadcasts. Both are managed within a unified GatewayModule, demonstrating a clean, modular design. This real-time layer is critical for delivering the live data insights that are central to the application's value proposition.