Architecture Note: Trello Real‑Time Board Synchronization via WebSocket

Requirements

\n

Trello must propagate card moves, comments, checklist updates, and label changes to all connected clients within sub‑second latency while preserving the existing per‑board permission model. The system should tolerate temporary network interruptions and eventually converge to a consistent state without requiring a full page reload.

\n\n

Smallest Suitable Design

\n

After a user authenticates via Trello’s REST API and receives a short‑lived JWT‑like token, the client opens a single secure WebSocket (wss://) to Trello’s real‑time service. The server streams JSON diff packets that describe add, update, or delete operations on board entities. The client applies these diffs to a local Redux‑style store, updating the UI instantly. To recover from missed diffs, the server periodically emits a full board snapshot that the client can merge into its local state.

\n\n

Trust and Data Boundaries

\n

The WebSocket endpoint validates the token issued by Trello’s authentication service. Before emitting any diff, the server checks the board‑level access control list (ACL) associated with the token. Consequently, a client never receives data for a board or card it is not authorized to see, enforcing the same trust boundary as the REST API.

\n\n

Operational Checks

\n

\n
1. Heartbeat/ping‑pong: The client sends a ping message (often labelled \"hb\" or \"ping\") every ~30 seconds and expects a pong response; absence of a pong triggers reconnection logic.
\n
2. Exponential back‑off reconnect: On disconnect, the client waits 2^n * baseDelay seconds (with jitter) before retrying, capping at a maximum delay to avoid thundering herd.
\n
3. Latency and loss monitoring: The client measures round‑trip time of heartbeats and counts missed diffs; high latency or loss can be logged for alerting.
\n
4. Snapshot recovery: Upon (re)connection, if the client detects a gap in diff sequence numbers, it discards buffered diffs and waits for the next full board snapshot to reconstruct state.
\n

\n\n

Failure Modes and Design Triggers

\n

\n
• Network partition: Diffs stop flowing; clients display stale UI until reconnection. After the partition heals, the heartbeat detects the loss, triggers reconnect, and a snapshot restores consistency.
\n
• Server overload: If the real‑time service begins dropping connections, clients fall back to REST polling (e.g., GET /1/boards/{id} every 15 seconds) as a degraded‑mode fallback.
\n
• Shift to CRDT or GraphQL subscriptions: Should Trello need stronger eventual‑consistency guarantees or want to reduce per‑client bandwidth, the current diff‑over‑WebSocket pipeline could be replaced by a conflict‑free replicated data type (CRDT) layer or GraphQL‑based live queries.
\n

\n\n

Practical Verification Steps

\n

\n
1. Open Trello in a desktop browser (Chrome, Firefox, Edge).
\n
2. Open Developer Tools → Network tab, enable the WS filter.
\n
3. Locate the WebSocket request; its URL will resemble wss://trello.com/1/... (the exact path is internal and may change).
\n
4. Select the WebSocket and view the Frames tab. You should see JSON messages such as:\n

   {\n  \"type\":\"card\",\n  \"action\":\"update\",\n  \"data\":{\n    \"id\":\"5f3a1b2c4d5e6f7g8h9i0j\",\n    \"name\":\"Updated Card Title\",\n    \"pos\":12345\n  }\n}

   \n This represents a card‑title update diff.
\n
5. Perform an action in the UI (e.g., move a card to another list). Observe a new diff frame reflecting the change.
\n
6. Simulate a network interruption: In DevTools → Network → Online, choose Offline. Verify that no further diff frames appear and the UI stops updating.
\n
7. Restore the connection (set back to Online). The client should first receive a full board snapshot (a large JSON object containing all cards, lists, etc.) followed by resumption of diff frames.
\n
8. Watch the console for heartbeat messages (often labelled \"hb\" or \"ping\"). Close the tab or disable the network; you should see reconnection attempts with increasing delays in the Network → WS log.
\n

\n\n

Limitations

\n

The exact WebSocket endpoint, message format, and heartbeat protocol are internal to Trello and may change without notice. Custom integrations that rely on undocumented details can break when Trello updates its real‑time engine. Additionally, the design assumes a reasonably stable internet connection; in high‑latency or frequently offline environments the client may show stale data for longer periods until a snapshot arrives.

\n\n

When to Reconsider the Design

\n

If Trello observes a significant increase in connected clients causing frequent connection drops, or if product requirements demand stronger conflict‑resolution semantics (e.g., collaborative editing of card descriptions), migrating to a CRDT‑based sync layer or adopting GraphQL subscriptions would be justified. Such a change would shift trust validation to the subscription layer but would preserve the same board‑level ACL checks.