Architecture

How the pieces fit together — from client to socket server to control plane.

System Overview

SummonFlow is split into three layers that communicate over standard HTTP and WebSocket protocols.

Client SDK

Runs in the browser or Node.js. Manages WebSocket connections, channel subscriptions, presence, and encrypted payloads.

Socket Server

Persistent process that handles WebSocket connections, message routing, and channel state. Deployed on Railway, Cloudflare, or your own infra.

Control Plane

The console app. Manages apps, keys, channel policies, webhooks, and billing. Hosted on Vercel.

Connection Flow

  1. Client initializes SummonFlow with an app key.
  2. WebSocket connection opens to the socket server.
  3. Server assigns a socketId and sends a connection event.
  4. Client subscribes to channels. Public channels connect immediately.
  5. Private/presence channels trigger an auth request to your backend, which signs the subscription.
  6. Server validates the signature and grants access to the channel.

Publish Flow

Server-side publishing is done via HTTP. Your backend sends a POST to the socket server with a publish token. The server broadcasts the event to all subscribers on the specified channel.

// Your backend publishes an event
POST /apps/:key/events
Authorization: Bearer <publish_token>
{ channel, event, data }

Scaling

For horizontal scaling, connect multiple socket server instances to a shared Redis instance. The Redis adapter handles message fanout so all connected clients receive events regardless of which server they're connected to.