Package Structure — EdgeStream Overview

Monorepo Layout

The EdgeStream monorepo lives at src/edge-stream/ in BizFirstAiStudio and is managed with pnpm workspaces. Packages are in packages/; runnable apps (DevTools, mobile dashboard) are in apps/.

src/edge-stream/
├── packages/
│   ├── edge-stream-js/          # Core runtime (framework-agnostic)
│   ├── edge-stream-js-react/    # React hooks and provider
│   ├── observability-core/      # IPipelineObserver contracts
│   ├── observability-hooks-js/  # HookActivityLogger
│   ├── observability-react/     # HooksMonitor, SubscribersMonitor
│   ├── observability-react-native/
│   ├── observability-ui/        # Shared UI primitives
│   ├── app-pages-react/         # Pre-built pages
│   ├── app-themes/              # Design tokens
│   ├── app-ui-components-react/ # Reusable UI components
│   └── utils/                   # Shared utilities
└── apps/
    ├── edge-stream-dev-tools/   # Full DevTools app
    └── mobile-dashboard/        # Lightweight mobile monitor

edge-stream-js — Core Runtime

The foundation of the entire system. This package has zero framework dependencies and runs in Node.js, browsers, and any JavaScript environment.

Internal Structure

edge-stream-js/src/
├── EdgeStream.ts        # Main facade class
├── index.ts             # Public API exports
├── types/               # All TypeScript interfaces
│   ├── envelope.types.ts
│   ├── hook.types.ts
│   ├── server.types.ts
│   ├── stream.types.ts
│   ├── subscription.types.ts
│   └── transport.types.ts
├── transports/          # SignalR, WebSocket, SSE, HTTP polling
├── pipeline/            # IncomingPipeline, OutgoingPipeline, PipelineContext
├── hooks/               # NormalizationHook, HookActivityLogger, base classes
├── subscriptions/       # SubscriptionManager, TopicMatcher, SubscriptionRegistry
├── servers/             # Server class
├── messaging/           # Message construction utilities
├── protocols/           # JSON, DIDComm-v2, CloudEvents parsers
├── adapters/            # Protocol adapters
├── logging/             # Module logger, log settings
├── observability/       # IPipelineObserver implementation
├── api/                 # API client helpers
└── services/            # Enterprise DI services

Key Exports

Export	Type	Purpose
`EdgeStream`	Class	Main facade — create via `createEdgeStream()`
`createEdgeStream`	Function	Factory for `EdgeStream` instances
`NormalizationHook`	Class	CloudEvents normalization hook
`HookActivityLogger`	Class	Observability hook for pipeline timing
`TopicMatcher`	Class	Wildcard topic pattern matching
`SubscriptionManager`	Class	Topic-based pub/sub registry
`BaseTransport`	Abstract Class	Base for custom transport implementations
`BaseHook`	Abstract Class	Base for custom hook implementations
`IEnvelope`	Interface	Universal message container type
`IHook`	Interface	Hook contract
`ITransport`	Interface	Transport contract
`VERSION`	Constant	Current library version (`'1.0.0'`)

edge-stream-js-react — React Bindings

React-specific wrappers that integrate EdgeStream with React component lifecycle. Subscriptions are automatically cleaned up on component unmount.

edge-stream-js-react/src/
├── context/
│   ├── EdgeStreamContext.tsx   # React context definition
│   ├── EdgeStreamProvider.tsx  # Provider component
│   └── types.ts                # ConnectionStatus, HealthStatus
├── hooks/
│   ├── useEdgeStream.ts        # Access EdgeStream instance
│   ├── useSubscription.ts      # Subscribe with auto-cleanup
│   ├── useConnectionStatus.ts  # Monitor connection state
│   └── useEdgeStreamSignalR.ts # SignalR-specific hook
└── components/                 # Pre-built UI components

observability-* Packages

observability-core

Defines the IPipelineObserver contract — the interface that hooks call to report execution events. This package has no UI dependencies and can be used in Node.js contexts.

observability-hooks-js

The HookActivityLogger implementation. Register this hook to capture timing and context for every hook execution. Its data feeds the HooksMonitor React component.

observability-react

Three React components for live pipeline monitoring:

HooksMonitor — live hook invocation log with timing and envelope preview
SubscribersMonitor — active subscriptions, topic patterns, delivery counts
ActivityStreamMonitor — combined activity feed

Installation Patterns

Minimal Installation (core only)

pnpm add edge-stream-js

React Application

pnpm add edge-stream-js edge-stream-js-react

With Observability

pnpm add edge-stream-js edge-stream-js-react observability-hooks-js observability-react

Full Stack (all packages)

pnpm add edge-stream-js edge-stream-js-react observability-core \
  observability-hooks-js observability-react app-ui-components-react

Internal Packages Only These packages are part of the BizFirstGO monorepo and are not published to the npm registry. Reference them via pnpm workspace protocol: "edge-stream-js": "workspace:*"

← Architecture Next: Core Concepts →