Design Case Studies · Lesson 18

Design: Slack API

Unlike consumer messaging apps, Slack is built around workspace hierarchies. An enterprise client with 100,000 members and thousands of channels presents a scaling profile where a simple connection boot can crash client apps, and broadcasting user presence creates O(N²) presence message cascades. Scaling Slack requires shifting from full synchronization to incremental subscription-driven APIs.

Requirements

Scaling a workspace-centric messaging platform introduces distinct constraints compared to point-to-point chat systems:

• Workspace Segmentation. Multi-tenancy must be enforced at the API layer. Users belong to workspaces, which contain channels (public, private, shared/Slack Connect). Permissions must resolve instantly.
• Avoid Reconnect Storms. When thousands of workers reconnect simultaneously (e.g., after a network blip), client boot queries must not overwhelm database and memory caches.
• Presence Management. Status changes (active, away, custom status) must propagate quickly, but must not cause an exponential bandwidth flood in large organizations.
• Slack Connect. Secure cross-workspace channel sharing, requiring the mapping of identities and message deliveries across independent tenant spaces.
• Real-time Delivery. Chat messages, typing states, and read markers must deliver with an end-to-end latency budget under 150 ms.

Design decisions

Transport: Connection Gateways & WebSocket Separation

To support millions of open TCP/TLS connections, Slack uses a dedicated gateway tier (such as Envoy proxies or custom Go/Edge proxies) to terminate WebSocket connections. These gateways do not hold application logic or state; they act as simple frame-forwarders. When a client reconnects, the gateway queries a distributed routing cache to locate the user's active session, then forwards incoming/outgoing frames. This protects internal database shards and application servers from direct exposure to TCP connection churn.

Boot Sync: Delta Syncing & Lazy Loading

In early iterations, Slack's `rtm.start` API returned the entire state of the workspace (all channels, members, history) in a single huge JSON block. For workspaces with over 10,000 users, this payload exceeded 50 MB, causing high latency, memory pressure, and client crashes.

The modern design uses a **Delta Sync API**. When the client boots or reconnects, it sends the timestamp of its last known state. The server returns only the differences (changes, additions, deletions). If the state is too stale, the client performs a bootstrap sync for the *sidebar content only* (subscribed channels and DMs), while lazy-loading members, profile cards, and channel archives as the user navigates the app.

Presence Service: Viewport-Driven Presence Subscriptions

In a workspace of 50,000 users, broadcasting every online/offline status change to all members generates $50,000 \times 50,000 = 2.5 \times 10^9$ updates — a massive performance bottleneck.

Slack solves this by shifting from global broadcast to **Presence Subscriptions**. The client app only subscribes to presence updates for users currently visible in the active sidebar viewport or active chat channel. As the user scrolls, the client dynamically unsubscribes from old IDs and subscribes to new ones over the WebSocket control channel, dropping presence delivery overhead by over 95%.

Shared Channels: Multi-Tenant Federation (Slack Connect)

Slack Connect allows two different organizations (Workspace A and Workspace B) to share a channel. To maintain tenant isolation, the channel exists as a federated resource. When a user in Workspace A posts a message, the API routes the request to Workspace A's regional databases. A background fan-out process detects the federated connection, duplicates the message, maps the sender's identity to a guest profile on Workspace B's domain, and pushes the event to Workspace B's message broker to deliver to Workspace B's active WebSocket sessions.

The API model

Establishing the Connection

Clients negotiate a WebSocket session by first requesting a gateway URL via a REST handshake. This allows load balancing and routing of the client to the closest edge datacenter.

# Request WebSocket gateway endpoint
POST /v1/apps.connections.open HTTP/1.1
Authorization: Bearer xoxb-token-123abc...
Content-Type: application/json

{
  "client_version": "desktop-4.32.0",
  "last_sync_timestamp": 1718908412
}

# Response returns gateway URL and synchronization payload
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "url": "wss://wss-edge-us-east.slack-edge.com/connection/v2/abc123xyz",
  "deltas": {
    "channels": {
      "added": ["C0123XYZ"],
      "removed": []
    },
    "users": {
      "updated": ["U999AAA"]
    }
  }
}

Presence Subscription Event

Once the WebSocket connection is open, the client sends subscription payloads to track presence updates for active viewports.

// Client → Server: subscribe to presence updates for visible users
{
  "type": "presence_sub",
  "ids": ["U111AAA", "U222BBB", "U333CCC"]
}

// Server → Client: status update for subscribed user
{
  "type": "presence_change",
  "user_id": "U222BBB",
  "presence": "active",
  "last_active": 1718908520
}

Under the hood: Slack connection scaling & pub/sub

To keep the chat experience fast, Slack decouples connection state from data writes. The Edge tier focuses on managing socket connections while the message routing tier routes events via localized Redis rings.

By the numbers: connection overhead & fan-out math

Let's evaluate the math behind scaling connections and presence changes inside a workspace of size $U$.

Governing Equations

• Total Connection Memory: The total RAM required to hold $N$ concurrent connections is: $$M_{total} = N \times (TCP_{buf} + TLS_{ctx} + WS_{state})$$
• Global Presence Broadcast: Broadcasting presence changes to every active user in a workspace with $U$ active users scales quadratically: $$Presence_{Broadcast} = U \times (U - 1) \times R$$ Where $R$ is the average status change rate per user per hour.
• Viewport Presence Subscription: If users subscribe only to visible sidebar profiles $V$ (where $V \ll U$): $$Presence_{Sub} = U \times V \times R$$

Scenario Parameters

• Workspace Size ($U$): 50,000 active users
• Active Sidebar Viewport Size ($V$): 40 profiles
• Status Change Rate ($R$): 1.5 changes per user per hour
• Memory Overhead per WebSocket Connection: 32 KB

Worked Calculations: Sync & Fan-out Comparison

Decision Math

When a channel size exceeds a threshold (e.g., $C > 2,000$), push-based typing updates and status changes are disabled. This bounds the maximum fan-out blast radius. The client falls back to **lazy polling** (checking status only when a user profile card is clicked) or **throttling push signals** to 10-second intervals.

How to debug & inspect it

To inspect active WebSocket traffic, use a command-line socket client like `wscat` to establish connection handshakes and intercept incoming frames.

Use the guide below to resolve common failures in workspace-centric real-time APIs:

{
  "workspace_id": "T0123ABCD",
  "last_sync_timestamp": 1718908412,
  "subscribed_channels": ["C0123XYZ", "C999888"]
}

{
  "sync_timestamp": 1718919212,
  "channels": {
    "created_or_updated": [
      { "id": "C0123XYZ", "name": "announcements-new", "topic": "Updated topic text" }
    ],
    "deleted": ["C8888999"]
  },
  "members": {
    "updated": [
      { "id": "U12345", "presence": "active", "status_text": "Out for lunch" }
    ],
    "deleted": ["U999111"]
  }
}

Sources & further reading

Original system design; these primary resources from Slack's engineering team describe the real implementation details:

• Slack Engineering — Flannel: edge cache to make Slack scale
• Slack Engineering — The Slack Real-time Messaging server architecture
• Slack Engineering — Under the Hood of Slack Connect/Shared Channels