{"id":22819668,"date":"2026-04-14T10:00:00","date_gmt":"2026-04-14T14:00:00","guid":{"rendered":"https:\/\/thenewstack.io\/?p=22819668"},"modified":"2026-04-13T17:16:56","modified_gmt":"2026-04-13T21:16:56","slug":"real-time-sync-engine","status":"publish","type":"post","link":"https:\/\/thenewstack.io\/real-time-sync-engine\/","title":{"rendered":"From clobbered drafts to real-time sync"},"content":{"rendered":"\n

Before writing the first line of code for Suga<\/a>, we knew we eventually wanted multiplayer interactions, so that teams could collaborate on projects. However, with a long feature wishlist already, we figured we could defer it until later as “nice to have”. So instead, the first canvas implementation was built with basic last-write-wins conflict resolution. <\/p>\n\n\n\n

Unfortunately, Jye and I figured out the hard way that our assumption about conflict resolution was pretty naive. Using an early build of Suga, we started working in a shared project at the same time without realizing. I was adding a service, along with its Postgres database, config, env vars, and tweaking positions so the layout made sense. Jye was on the other side of the project, adding functions and coding up integrations.<\/p>\n\n\n\n

Changes get saved as a draft automatically as you work, so every time one of us moved a node or added a connection, the draft updated. However, because there was no merging, each save just replaced the entire draft with whatever the client had. My saves were silently overwriting Jye’s work, and his were overwriting mine. When Jye refreshed the browser tab, everything he’d built was gone, since I’d made the most recent change, the last draft write was mine. We do automatically track a project’s history, but only for deployed changes, so because none of this had been deployed yet, it was just lost.<\/p>\n\n\n\n

It made it obvious that last-write-wins for the entire canvas wasn’t going to work. Although we could have improved the situation with other locking\/conflict resolution techniques, we knew we wanted full multiplayer eventually, so real-time sync was the right choice.<\/p>\n\n\n\n

Have you looked at sync engines?<\/h2>\n\n\n\n

If you’re unfamiliar with sync engines, Jye got kind of obsessed with them last year and wrote a blog about it<\/a>. I’d also recently watched a Syntax video<\/a> where they used Zero to build a competitive coding game, and the sync model clicked immediately. In our next standup, we both agreed we needed to drop other features and get this built.<\/p>\n\n\n\n

We ended up going with Zero<\/a>, which is a sync engine from Rocicorp. Basically, every client gets a local SQLite database that stays in sync with our PostgreSQL on the server. Writes happen locally first, then are replayed on the server; if there’s a conflict, the server wins, and clients reconcile automatically.<\/p>\n\n\n\n

Why Zero and not something else? CRDT libraries like Yjs and Automerge are designed for document-style collaboration, things like text editors and drawing tools. Our data is relational<\/a> Postgres rows, including some larger JSONB columns. Tools like ElectricSQL and PowerSync also sync Postgres, but Zero’s mutator<\/a> model gave us fine-grained control over conflict resolution for JSON values.<\/p>\n\n\n\n

Two kinds of changes<\/h2>\n\n\n\n

We realized early that not all changes are equal; some can be merged, some can’t, and some can tolerate last-write-wins. Figuring out which was which turned out to be the core design problem. The canvas is built on React Flow<\/a>, and every interaction that changes state goes through a Zero mutator.<\/p>\n\n\n\n

\n

“Figuring out which was which turned out to be the core design problem.”<\/p>\n<\/blockquote>\n\n\n\n

\"Diagram<\/figure>\n\n\n\n

<\/p>\n\n\n\n

Granular mutators<\/h3>\n\n\n\n

The canvas node positions are stored as a single JSON value for simplicity. What we want is when I drag a node, only that node’s position changes. If someone else drags a different node at the same time, both writes land cleanly, without conflict. If we somehow drag the same node simultaneously, the last write wins, since that’s fine for node positions where there’s no meaningful way to merge them and the data isn’t critical. If I place a node at (400, 200) and Jye places one at (600, 300), one of us will win.<\/p>\n\n\n\n

Here’s what that mutator looks like for node positions:<\/p>\n\n\n

\ntypescript\nexport const updateNodePosition = defineMutator(\n  z.object({ environmentId: z.string(), nodeId: z.string(), position: PositionSchema }),\n  async ({ tx, ctx, args: { environmentId, nodeId, position } }) => {\n    \/\/ Access check runs server-side only\n    if (tx.location === "server") {\n      await verifyAccess(tx, environmentId, ctx.activeOrganizationId);\n    }\n\n    const env = await getEnvironment(tx, environmentId);\n\n    \/\/ Spread existing positions, overwrite just this node\n    await tx.mutate.environment.update({\n      id: environmentId,\n      canvasMetadata: {\n        ...env?.canvasMetadata,\n        nodePositions: {\n          ...env?.canvasMetadata?.nodePositions,\n          [nodeId]: position,\n        },\n      },\n    });\n  },\n);\n<\/pre><\/div>\n\n\n
The spread is the key part: we read the current positions and overwrite only the one node. On the client, this reads from local cache; on the server, it reads from the database. Both run the same function, but the server’s view is authoritative.<\/p>\n\n\n\n
\n
“The spread is the key part: we read the current positions and overwrite only the one node… the server’s view is authoritative.”<\/p>\n<\/blockquote>\n\n\n\n
A similar pattern applies to infrastructure changes, which is what fixed our clobbering problem. When I add a service, the mutator reads the current compute array, appends mine, and writes it back. If someone else adds a function at the same time, their mutator does the same. The server replays both, and the result has both changes.<\/p>\n\n\n
\ntypescript\nexport const addCompute = defineMutator(\n  z.object({\n    environmentId: z.string(),\n    compute: ComputeSchema,\n    position: PositionSchema.optional(),\n  }),\n  async ({ tx, ctx, args: { environmentId, compute, position } }) => {\n    \/\/ ... same access check pattern\n\n    const env = await getEnvironment(tx, environmentId);\n    const def = env?.draftDefinition;\n\n    \/\/ Read current computes, append the new one, write it back\n    const updatedDef: ProjectDefinition = {\n      version: "v1",\n      computes: [...def.computes, compute],\n      volumes: def.volumes,\n    };\n\n    await tx.mutate.environment.update({\n      id: environmentId,\n      draftDefinition: updatedDef,\n      \/\/ ... also sets node position on canvas if provided\n    });\n  },\n);\n<\/pre><\/div>\n\n\n
We considered using CRDTs<\/a> to merge these changes, but our data model would require significant work to decompose into CRDT-friendly structures. Building a custom<\/a> CRDT would have added complexity without a clear win over last-write-wins for positions, or read-modify-write for computes.<\/p>\n\n\n\n
Bulk mutators<\/h3>\n\n\n\n
Some operations can’t be granular; for example, undo<\/code> replaces the entire canvas with a previous snapshot. Deploy and discard do the same.<\/p>\n\n\n
\ntypescript\nexport const updateDraftAndCanvas = defineMutator(\n  z.object({ environmentId: z.string(), draftDefinition: ProjectDefinitionSchema, canvasMetadata: CanvasMetadataSchema }),\n  async ({ tx, ctx, args: { environmentId, draftDefinition, canvasMetadata } }) => {\n    \/\/ ... same access check\n\n    \/\/ No spread, no merge. Just replace everything.\n    await tx.mutate.environment.update({\n      id: environmentId,\n      draftDefinition,\n      canvasMetadata,\n    });\n  },\n);\n<\/pre><\/div>\n\n\n
There is currently no merging here; the snapshot wins. That’s the right tradeoff for undo, where the intent is “go back to exactly this state.”<\/p>\n\n\n\n
Drizzle as the schema source of truth<\/h2>\n\n\n\n
We use Drizzle<\/a> as our ORM. Its schema definitions double as the source of truth for Zero’s sync schema.<\/p>\n\n\n
\ntypescript\nexport const environment = pgTable('environment', {\n  id: uuid('id').primaryKey().defaultRandom(),\n  projectId: uuid('project_id').references(() => project.id),\n  canvasMetadata: jsonb('canvas_metadata').$type&lt;CanvasMetadata>(),\n  draftDefinition: jsonb('draft_definition')\n    .default(InitialProjectDefinition)\n    .$type&lt;ProjectDefinition>(),\n  \/\/ ...\n});\n<\/pre><\/div>\n\n\n
Two JSONB columns hold the collaborative state: canvasMetadata<\/code> for positions and sticky notes, draftDefinition<\/code> for the infrastructure graph. The alternative would be to normalize into separate tables, which would give zero row-level diffs. We chose JSONB for now because it’s simpler and the mutator-level merge gives us enough control. If we hit scaling issues, normalizing is the obvious next step.<\/p>\n\n\n\n
A few gotchas we hit:<\/p>\n\n\n\n