WebSocket & Display Routes
Relevant source files
The following files were used as context for generating this wiki page:
The WebSocket and Display infrastructure facilitates real-time communication between the automation server and the frontend client. This system is responsible for broadcasting live logs, automation status updates, and progress metrics, while the associated display routes (managed under the workflows and automation modules) handle the retrieval of artifacts and VNC-related session information.
These components ensure that users have an immediate view of the automation runtime, including specific details about which profile is active, which task is being executed, and the results of scraping operations.
WebSocket Architecture
The WebSocket implementation uses a centralized server-side hub to manage authenticated client connections and broadcast events generated by the automation engine.
Server-Side Implementation
The server initializes a WebSocketServer at the /ws path. Security is enforced via Clerk authentication; clients must provide a valid JWT in the connection query string (?token=xxx). Upon connection, the server immediately sends the current automationState.status to the client.
The broadcast function is the primary interface for sending data to all connected clients. It handles specific message types, such as logs, by storing them in an in-memory logsStore and appending them to a persistent file log before transmission.
Sources: [server/websocket.ts:10-38](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/websocket.ts#L10-L38), [server/index.ts:31-33](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/index.ts#L31-L33)
Client-Side Integration
The frontend utilizes the useWebSocket hook to manage the lifecycle of the connection. This hook implements an exponential backoff strategy for reconnections and includes a "pause when hidden" feature to conserve resources when the browser tab is inactive.
Sources: [frontend/src/hooks/useWebSocket.ts:167-205](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L167-L205), [frontend/src/hooks/useWebSocket.ts:46-52](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L46-L52)
Message Flow Diagram
The following diagram illustrates the lifecycle of a WebSocket connection from authentication to real-time broadcasting.
Sources: [server/websocket.ts:12-51](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/websocket.ts#L12-L51), [frontend/src/hooks/useWebSocket.ts:145-165](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L145-L165)
Communication Protocols
The system defines a structured messaging protocol for different types of automation events.
Message Types and Schema
WebSocket messages are JSON objects containing a type field and associated metadata.
| Message Type | Description | Key Fields |
|---|---|---|
log | Real-time execution logs | message, level, source, workflowId |
status | Global automation state | status (idle, running, stopping) |
workflow_status | Specific workflow state | workflowId, status |
session_started | New automation session | total_accounts |
profile_started | Automation started for a profile | profile |
display_allocated | VNC display resource assigned | display_num, vnc_port |
Sources: [frontend/src/hooks/useWebSocket.ts:13-43](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L13-L43), [server/websocket.ts:45-66](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/websocket.ts#L45-L66)
Log Parsing and Buffering
On the frontend, logs are parsed into a LogEntry structure and stored in a circular buffer controlled by maxBuffer (default 500 entries). This ensures the UI remains performant during high-volume logging.
Sources: [frontend/src/hooks/useWebSocket.ts:60-78](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L60-L78), [frontend/src/hooks/useWebSocket.ts:106-121](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L106-L121)
Workflow and Display Data Routes
The Display-related functionality is integrated into the workflow routes to provide access to artifacts and live execution data.
API Endpoints
These routes provide the necessary data for the frontend to render the status of workflows and download generated artifacts.
| Endpoint | Method | Description |
|---|---|---|
/api/workflows/status | GET | Returns current status of a specific workflow ID. |
/api/workflows/artifacts | GET | Lists all scraping artifacts for a workflow. |
/api/workflows/artifacts/storage-url | GET | Gets a temporary download URL from Convex storage. |
/api/workflows/artifacts/download | GET | Proxies artifact download with correct headers. |
Sources: [server/workflows/routes.ts:25-88](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/workflows/routes.ts#L25-L88)
Artifact Management Logic
The server interacts with a Convex backend to retrieve artifact metadata and storage IDs. When a download is requested, the server fetches the file from the underlying storage cloud and streams it to the client as an attachment.
Sources: [server/workflows/routes.ts:65-88](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/workflows/routes.ts#L65-L88), [server/shared/convexClient.ts:394-406](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/shared/convexClient.ts#L394-L406)
Display Resource Management
While "Display" routes are mentioned as a separate router in the main index, the logic primarily revolves around VNC allocation and process tracking.
- VNC Ports: The WebSocket messages
display_allocatedanddisplay_releasedtrack the mapping of automation profiles to VNC displays and ports (e.g.,vnc_portanddisplay_num). - Process Cleanup: The server runs
cleanupOrphanedProcesseson startup to ensure no stale display or automation processes remain from previous sessions.
Sources: [frontend/src/hooks/useWebSocket.ts:39-42](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/frontend/src/hooks/useWebSocket.ts#L39-L42), [server/index.ts:143-145](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/server/index.ts#L143-L145), [AGENTS.md:23-31](https://github.com/yaroslavchybar/bot-auto-ig/blob/HEAD/AGENTS.md#L23-L31)
Summary
The WebSocket and Display Route system provides the real-time backbone of the application. By combining authenticated WebSocket streams for status and logs with a robust HTTP API for artifact retrieval, the system ensures that automation execution is transparent and that data results are easily accessible to the user. The architecture prioritizes reliability through automatic reconnection logic and server-side state reconciliation.