Architecture

EdgeStream is a 14-package TypeScript monorepo organised in a strict layered architecture. Each message travels through a deterministic pipeline — validated, normalised, filtered, logged, and delivered with a complete audit trail.

Package Layers

Packages are organised in three layers. Each layer may only depend on packages in layers below it — no upward dependencies, no circular imports.

Layer 2 — Framework Adapters

Platform-Specific Integrations

edge-stream-js-react edge-stream-js-react-native @edge-stream/observability-react

React Provider, hooks (useEdgeStream, useSubscription, usePublish, useConnectionStatus). React Native adapter. Inspector UI for observability. Zero server dependencies.

↓

Layer 1 — Observability

Metrics, Logging & Health

observability-core observability-hooks-js @edge-stream/inspector

Activity logging with LRU eviction, per-hook metrics, health check endpoints, real-time inspector app. Queryable by message ID, topic, source, or status. Export as JSON.

↓

Layer 0 — Core Infrastructure

Pipeline, Transport & Pub/Sub

edge-stream-js utils @edge-stream/signalr-server @edge-stream/websocket-server @edge-stream/http-transport

EdgeStream facade, Pipeline executor, SubscriptionManager, ConnectionManager, HookActivityLogger, SubscriberActivityLogger, LoggingService. IEnvelope + CloudEvents standard. Zero external npm dependencies.

14 packages — each with one job

edge-stream-js

Core library — EdgeStream facade, Pipeline executor, SubscriptionManager, HubServer, WebSocketServer, ConnectionManager, HookActivityLogger, SubscriberActivityLogger, LoggingService. ~15KB minified.

utils

Shared utility functions — deepClone, diffEngine, formatters, validators. Zero external dependencies. Used by every other package.

observability-core

Metrics and activity logs — ActivityLog, MetricsCollector, HealthCheck. Configurable LRU log storage. Query by status, serverId, topic, source. Performance statistics: slowest hook, success rate, throughput.

observability-hooks-js

Hook-specific observability — HookMetrics, HookTracer, ExecutionTimingAnalyzer. Per-hook success/error rates. Hook dependency graph analysis and performance profiling.

@edge-stream/signalr-server

SignalR transport adapter — HubServer implementation wrapping @microsoft/signalr. Auto-reconnect strategy, group management (joinGroup/leaveGroup), connection lifecycle events.

@edge-stream/websocket-server

WebSocket transport adapter — direct WebSocket connections without SignalR. Same IServer interface as HubServer — swap transports without changing application code.

@edge-stream/http-transport

HTTP fallback transport — long-polling for environments where WebSocket is unavailable. Seamlessly used alongside other transports.

edge-stream-js-react

React integration — EdgeStreamProvider, useEdgeStream(), useSubscription(), usePublish(), useConnectionStatus(), useObservability(). Full TypeScript strict mode.

edge-stream-js-react-native

React Native adapter — same EdgeStream API surface with mobile-specific transport layer. Supports offline message queuing and background reconnection.

@edge-stream/observability-react

React components for observability — real-time activity feed, hook performance graphs, connection status indicators, subscriber delivery viewer.

@edge-stream/inspector

Standalone inspector application — real-time message flow visualisation, hook execution timeline, subscriber delivery map. Development and staging tool.

@edge-stream/azure-signalr

Azure SignalR Service adapter — horizontal scaling beyond a single SignalR hub. Group broadcast, connection management, and fan-out via Azure infrastructure.

@edge-stream/kafka-adapter

Kafka integration — durable message streaming for high-throughput scenarios. Bridges EdgeStream's in-process pub/sub to Kafka topics for cross-service event distribution.

@edge-stream/mcp-server

Model Context Protocol server — exposes EdgeStream pub/sub to AI agents and LLM toolchains. Enables AI agents to subscribe to topics and publish messages natively.

Hook pipelines — incoming and outgoing

Every message passes through a deterministic hook pipeline before reaching subscribers. Hooks are ordered by priority, composable, and independently testable.

Incoming Pipeline (9 hooks)

Hook	Priority	Purpose
pre-pipeline	0	Early interceptors, rate limiting
validation	10	Schema validation, envelope structure check
normalization	20	Convert to IEnvelope + CloudEvents format
filter	30	Drop messages not matching subscription patterns, security checks
log (incoming)	40	Record arrival, source, metadata, processing start time
enrichment	50	Add business context, user data, entity information
routing	60	Resolve destination subscribers via topic matching
custom hooks	70+	User-defined transformation, third-party integrations
post-pipeline	100	Final processing before pub/sub delivery

Outgoing Pipeline (5 hooks)

Hook	Priority	Purpose
pre-pipeline	0	Early interceptors, outgoing validation
transformation	10	Convert app format → transport format, add timestamp and routing metadata
log (outgoing)	20	Record send, destination, metadata for audit trail
retry	30	Queue failed messages with exponential backoff
custom hooks	40+	Post-send processing, webhook triggers, notifications

The IEnvelope — what every message carries

IEnvelope is the canonical message format. It is CloudEvents-compliant and wraps every message with routing metadata, body, headers, and custom attributes.

IEnvelope.meta

messageIdstring (UUID)

correlationId?string

sourcestring

topicstring

timestampISO8601 string

conversationId?string

userId?string

IEnvelope.body

text?string

type?string

data?Record<string, unknown>

contentType?string

IEnvelope.headers

specversion'1.0' (CloudEvents)

typestring (event type)

idstring (CloudEvents ID)

timeISO8601 string

datacontenttype?'application/json'

IEnvelope.attributes

priority?'low'|'normal'|'high'

ttl?number (milliseconds)

routing?Record<string, string>

[key: string]unknown

Message lifecycle — from send to delivery

Every message follows the same deterministic path. Every stage is logged. Every failure is captured with full context for debugging and compliance.

1

Application publishes

edgeStream.publish({ topic, body, meta }) — enters the outgoing pipeline immediately.

2

Outgoing pipeline executes

Transformation → Log → Retry hooks fire in priority order. Message is normalised and validated before leaving the client.

3

Transport layer transmits

SignalR, WebSocket, or HTTP transport sends the serialised IEnvelope to the server. Connection manager handles retries on transport failure.

4

Server processes

Backend receives the envelope, executes business logic (workflow, form validation, AI response), and may publish a response message back via EdgeStream.

5

Incoming pipeline runs

Pre-pipeline → Validation → Normalization → Filter → Log → Enrichment → Routing → Custom hooks — in priority order. Failed validation drops the message and logs the error.

6

Pub/Sub Engine delivers

SubscriptionManager matches the topic against all registered subscriptions — exact, prefix, and wildcard. Matching subscribers receive the full IEnvelope.

7

Subscriber callbacks execute

Each matching subscriber's callback fires with the complete IEnvelope. Execution time, success, and errors are recorded by SubscriberActivityLogger.

8

Audit trail complete

Full message lifecycle queryable by messageId. HookActivityLogger + SubscriberActivityLogger provide every timing, status, and error for compliance and debugging.