EdgeStream Overview
A professional TypeScript real-time message pipeline framework for orchestrating workflows, managing real-time messaging, and automating UI interactions across BizFirstGO.
What is EdgeStream?
EdgeStream is the real-time message delivery backbone of BizFirstGO. It provides a composable, hook-driven pipeline for moving typed messages between backend services and frontend applications. Built as a 10-package TypeScript monorepo, EdgeStream handles everything from raw transport connections to structured pub/sub delivery — with full observability built in.
Every real-time event in BizFirstGO passes through EdgeStream: workflow execution updates, Octopus agent responses, ANCP protocol messages, and UI interaction events. The library is framework-agnostic at its core with a dedicated React bindings package for frontend integration.
edge-stream-js package (108KB compiled) is the complete framework-agnostic runtime. Import it in any TypeScript/JavaScript environment. React-specific features live separately in edge-stream-js-react.
Key Capabilities
Typed Message Pipeline
Every message flows through an ordered series of hooks — normalization, transformation, delivery — with full TypeScript generics throughout.
Multi-Transport
SignalR (recommended), raw WebSocket, SSE, and HTTP polling — each transport implements the same ITransport interface.
Topic-Based Pub/Sub
Subscribe to exact topics or wildcard patterns (workflow.*). Subscribers receive typed IEnvelope containers.
Composable Hooks
Add cross-cutting behavior — logging, validation, transformation, auth — as discrete hook classes with priority ordering.
Built-in Observability
HooksMonitor and SubscribersMonitor React components visualize live pipeline activity in real time.
React Bindings
useSubscription, useEdgeStream, and EdgeStreamProvider make real-time subscriptions clean in React components.
Message Flow at a Glance
Every incoming message follows the same linear path from transport receipt to subscriber delivery:
Transport Receipt
Raw bytes arrive over SignalR, WebSocket, SSE, or HTTP polling. The transport emits a raw message event.
Normalization
NormalizationHook converts raw data into a standardized IEnvelope with CloudEvents protocol metadata. Business data is never modified.
Incoming Pipeline
Registered hooks execute in priority order — validation, decryption, logging, enrichment. Any hook can abort the pipeline.
Subscriber Delivery
SubscriptionManager matches the envelope topic against registered patterns and invokes all matching subscriber callbacks.
Observability
Every step emits events to IPipelineObserver — feeding HooksMonitor and SubscribersMonitor in real time.
The Ten Packages
| Package | Purpose | Key Exports |
|---|---|---|
edge-stream-js | Core runtime — pipeline, hooks, subscriptions, transports | EdgeStream, createEdgeStream, all types |
edge-stream-js-react | React hooks and context provider | EdgeStreamProvider, useSubscription, useEdgeStream |
observability-core | Observer contracts — IPipelineObserver | IPipelineObserver, event types |
observability-hooks-js | Hook that feeds observability data | HookActivityLogger |
observability-react | React monitoring components | HooksMonitor, SubscribersMonitor, ActivityStreamMonitor |
observability-react-native | React Native monitoring components | Mobile equivalents of react components |
observability-ui | Shared UI primitives for observability | Charts, lists, activity feeds |
app-pages-react | Pre-built React pages for EdgeStream apps | Dashboard, settings pages |
app-themes | Theming tokens for EdgeStream apps | Color tokens, design system |
app-ui-components-react | Reusable React UI components | Buttons, panels, status indicators |
Where EdgeStream is Used in BizFirstGO
- Flow Studio Observer Panel — workflow execution events (
NodeExecutionStarted,NodeExecutionCompleted) are delivered via EdgeStream SignalR transport - Octopus Agent Chat — each LLM streaming token is an EdgeStream message on the
agent.*topic namespace - HIL (Human-in-the-Loop) — approval requests and responses flow through EdgeStream for real-time suspension/resume
- ANCP Protocol — Agent Node Communication Protocol messages use EdgeStream as their delivery layer
- WorkDesk Notifications — real-time notifications for task assignments, approvals, and workflow completions