← All posts

Realtime from backend to browser

Most of what the realtime system does is invisible. A stock update made on one device appears on another. A batch state change propagates to every screen that cares about it. Nobody had to refresh. This post covers how that works end to end, from a write on the backend to a screen update in the browser.

What we built

The realtime system has two halves that mirror each other. On the backend, the RealtimeHub receives a notification after every write, buffers those notifications into account-scoped batches, and flushes them to connected devices after a short window. On the frontend, the realtime service receives those batches, queues them for processing, and translates each one into the scope invalidation mechanism the data layer already uses.

The transport is Socket.IO, sitting behind the same port/adapter contract as the ORM and the mail channel. The frontend never imports socket.io-client directly. Neither half knows what the other is built on.

The problem it solves

The previous post described how the frontend data layer works: a normalised local store, scopes that track what the client holds completely, and refetches triggered when a scope goes dirty. What it did not cover is how those scopes go dirty in response to changes made by other people.

Plan.Make.Trace is used collaboratively. More than one person may be working in the same account at the same time, on different devices, in different parts of the workshop. Without realtime, those users are looking at state that diverges from reality the moment someone else makes a change. A polling approach either hammers the server or leaves the UI stale. Neither is good enough for a manufacturing application where the current state of stock and production actually matters.

The realtime system exists to close that gap cleanly, without requiring every screen or every domain to wire up its own subscription logic.

How the backend side works

Every write can notify the realtime system about what changed. Rather than broadcasting immediately, those changes are collected into a short account-scoped batch before being flushed to connected devices.

When the window closes, the hub coalesces the buffer. Multiple writes to the same record within the window collapse down to the latest state. Then, before anything is broadcast, the hub checks the access engine. For each profile currently connected to the account, it filters the event set down to records that profile is permitted to read. A profile only learns that a record changed if it would be allowed to fetch that record.

The result is delivered to a profile-scoped room rather than an account-scoped broadcast. Each device receives only what it is permitted to know about.

How the frontend side works

On the frontend, incoming dirty batches enter a queue before they touch local state. The queue processes in FIFO order. A record that is already being reconciled stays queued until reconciliation is done, so two rapid deliveries for the same record cannot interleave.

Processing a batch calls into the same scope invalidation path that any other data layer operation uses. A deleted record gets tombstoned and removed from the store. An updated record marks its scope dirty. A dirty scope triggers a refetch through the domain store's existing reconciliation loop. There is no realtime-specific code downstream of that translation step.

Changes the user originated themselves are still reconciled, but not announced. The person who performed an action already received immediate feedback from doing it. Quietly updating the local store without surfacing a notification is the right behaviour for their own screen. Other users on the account still see the appropriate feedback.

Recovery

A socket connection is not guaranteed. A device can go offline, switch networks, or simply lose the connection between dirty events. The question is what happens when it reconnects.

The hub maintains a per-device ledger of dirty state that has not yet been acknowledged. When a device reconnects, it sends a recover request and receives everything that accumulated in its ledger while it was gone. It processes that backlog through the same queue as live events. From the data layer's perspective, recovery and live delivery are the same operation.

If the ledger is too old to be reliable, the hub says so and the client performs a full refresh instead of trying to reconcile against history it cannot trust. The goal is that reconnecting devices catch up to current state accurately, even when the connection was interrupted for long enough that the history is uncertain. Factory Wi-Fi is not the most reliable environment, and the system needs to behave correctly in it.

The deliberate tradeoff

The system sends invalidation signals, not replicated application state. The backend says what became dirty. The frontend's normal data path determines what the current state actually is. The realtime layer is thin by design.

This means realtime does not need to understand business logic, field-level access rules, or how records compose. All of that lives in the REST path, where it already works. Realtime is purely a signal: something changed, here is what, go find out the current state through the channels that know how to answer that question correctly.

For the initial product, the priority is keeping the application current across the kinds of connectivity interruptions that actually happen in a workshop. Full replay and richer offline capability remain available as future extensions if that requirement becomes important.

What's next

That completes the core infrastructure story. The next post covers the production batch workflow: how Plan.Make.Trace takes a recipe through manufacturing, connects the stock it consumes, and produces the finished goods that go out.

Liked this post? Tap the heart to let us know.

Get early access

Be the first to hear about early access, roadmap updates, and exclusive early adopter pricing.

Join the early access list