Skip to main content
This section documents the B Brands realtime layer built on Pusher Channels. horizon-api publishes typed domain events (digital-contract lifecycle, Maihue Street / NOC telemetry) to per-entity channels; frontends subscribe and react to them.

​
What this is

Realtime is a best-effort UX enhancement layered on top of the authoritative REST/query state — never a source of truth. When a backend action should reach a connected client immediately (a contract is signed, a totem sends a telemetry frame, a NOC alert fires), the server triggers a Pusher event on the channel that owns that entity. The client reacts, typically by invalidating a cached query.

What realtime does

Pushes a lightweight notification so the UI refreshes without waiting for the next poll.

What realtime does NOT do

It never carries authoritative state and never guarantees delivery. If a message is missed, the REST/query layer is still correct.

​
Graceful degradation

Pusher credentials are optional in every environment:
  • Without server credentials, the publisher runs in log-only mode (the trigger is a no-op) and never throws.
  • Without a client key, the subscription hook reports status: "disabled" and consumers fall back to polling.
Never treat a Pusher event as a transactional signal. Every consumer must remain correct if the event is dropped, duplicated or arrives out of order.

​
How the signal flows

​
Where to go next

Architecture

The publisher, the lazy client and the degradation model.

Channels & Events

Channel naming, the event contract and the private-channel authorizer.

Client Integration

The shared usePusherChannel hook and the client env contract.

Operations

Environment variables, health probe and troubleshooting.