Multiplayer Canvas at Scale: Socket.IO + Redis Adapter Inside AACFlow

That also gives us a clean unit of horizontal partitioning. Workflow A's traffic never touches workflow B's subscribers, so a noisy enterprise canvas with 40 active editors never starves the rest of the cluster.

Why @socket.io/redis-adapter Replaces Sticky Sessions

In production, AACFlow's realtime tier runs as a fleet of pods behind a load balancer. Without an adapter, a user landing on pod A and another user landing on pod B would never see each other's edits — they would be in two disjoint room registries.

The classic fix is sticky sessions: pin all members of a room to the same pod. We rejected that. Sticky sessions break autoscaling, complicate blue-green deploys, and create a single point of failure per workflow.

Instead we wire @socket.io/redis-adapter into the Socket.IO server. Every io.to(room).emit(...) call publishes to a Redis pub/sub channel; every pod subscribes; every pod re-fans-out to its own local clients. The result: user on pod A drags a block, user on pod B sees the move 5–20 ms later, no stickiness, no affinity required.

The cost is one extra Redis hop per emit. We pay it gladly. Horizontal scale is now an operational decision, not an architectural one.

Conflict Resolution: LWW for Positions, OT for Text

Multiplayer is not just about delivery — it is about what happens when two people move the same block at the same time, or edit the same prompt body two characters apart.

AACFlow uses two strategies side by side:

• Last-write-wins for positions. Block coordinates, port handles, zoom level. The latest timestamped event wins. If you and a teammate both grab the same block, the final position is whoever let go last. This is correct, predictable, and cheap.
• Operational transform for text fields. Prompt bodies, code blocks, long-form descriptions. Inserts and deletes are transformed against concurrent operations so character offsets remain valid. No "I just lost my paragraph" moments.

We deliberately do not run a single global CRDT for the entire workflow. Positions and text have different convergence requirements, and conflating them into one structure wastes bytes and CPU on every cursor move.

Reconnect: Snapshot On Join, Diff Replay

Networks drop. Pods restart. Laptops sleep. The reconnect protocol has to be boring — meaning the user does not notice it happened.

When a client (re)joins a room, the server sends a current snapshot of the workflow's runtime state: blocks, edges, subblock values, last-known cursor positions of other members. The client then subscribes to the live event stream. Any events the server buffered for that client during the disconnect window are replayed as a compact diff before live traffic resumes.

The snapshot is the source of truth on join; the event stream is the source of truth after. If the two ever disagree, we trust the snapshot and re-emit. This is what keeps two users from drifting into divergent canvases after one of them hibernates a tab for an hour.

The Hook That Holds It All: use-collaborative-workflow

On the client, every page route mounting the canvas wires up a single hook: use-collaborative-workflow.tsx. It is around 62 KB of source — large because it has to coordinate Socket.IO, the Zustand workflow store, the undo/redo stack, optimistic updates, and the local React Flow viewport.

The hook exposes a flat API to the canvas components: applyRemoteBlockUpdate, broadcastLocalEdit, subscribeToPresence. Every callback is wrapped in a stable ref so React 19 doesn't trigger renders on remote updates that don't affect the current viewport. The store, not the hook, owns truth — the hook is just the bridge.

We resisted breaking the hook into ten smaller hooks. Multiplayer is intrinsically stateful, and splitting it forced too much shared state across module boundaries. One big hook, one big test file, one place to grep when something goes wrong.

HMR Orphan Sockets and Other Operational Bites

There is one local-dev gotcha worth naming. Next.js HMR can leave orphan socket clients holding Redis pub/sub channels. The symptom: edits appear to lag, then double up, then stop. The cause: the previous module instance is still subscribed and still draining events into a dead React tree.

The fix is in CLAUDE.md as a known gotcha: restart dev:sockets before debugging the adapter. We also added a defensive disconnect on module hot-reload, which catches most cases. It is the kind of bug that does not exist in production but eats an afternoon if you don't know about it.

Multiplayer Is The Default, Not A Feature Flag

The point of all this plumbing is that on AACFlow the multiplayer canvas is not a toggle you turn on for the Enterprise tier. It is how the product works. A solo user opening their own workflow runs through the exact same Socket.IO + Redis pipeline as a ten-person team editing in parallel.

That means the system is exercised on every session, the failure modes are visible early, and the scaling story is honest — we have already paid the cost of multiplayer for every user, so onboarding a team is zero new infrastructure.

If your platform still treats real-time as an add-on, you have not yet had the conversation. Put the canvas in a room, give the room a Redis adapter, and let the third user in. Everything else is plumbing.