Architecture

EdgeInteract is a 13-package TypeScript monorepo built in a 7-layer system. Each layer can only depend on layers below it. Context flows upward through every message — never sideways or lost.

7-Layer System Architecture

EdgeInteract sits in layers 2A and 3A. EdgeStream is the foundation at Layer 0. No upward dependencies allowed.

Layer 3C — Future
Framework Adapters
@edge-interact/vue @edge-interact/angular @edge-stream/react-native
Future framework bindings — roadmap Phase 5.
↓
Layer 3A — EdgeInteract UI
React Components & Pages
@edge-interact/react-ui @edge-interact/react-hooks @edge-stream/observability-react
EdgeInteractProvider, useEdgeInteract(), useChat(), useForm(), useWorkflow(). ChatPage, FormPage, DashboardPage. React 18 + TypeScript.
↓
Layer 2A — EdgeInteract Core
Design System & Integration
@edge-interact/ui @edge-interact/integration @edge-interact/client @edge-interact/built-in-plugins @edge-interact/plugins-core @edge-interact/player-manager @edge-interact/context-manager @edge-interact/comm-manager @edge-interact/chat-window
Three-manager architecture. Plugin system. 6 Zustand stores. 5 API clients. Design tokens. Vanilla JS chat widget.
↓
Layer 1 — Utilities
Shared Utilities
@edge-stream/utils
Deep clone, diff engine, shared utility functions.
↓
Layer 0 — Foundation
EdgeStream Core
edge-stream-js @edge-interact/context-data-js @edge-interact/context-data-samples-js
Pipelines, hooks, pub/sub, servers, observability, routing. Zero UI dependencies. Canonical context types. Domain sample types (CRM, Healthcare, E-Commerce).

13 packages — each with one job

@edge-interact/context-data-js
Canonical data types — IUserData, ISessionData, IConversationData, IEntityIdentityData, IContextualMessage. Zero external dependencies. Used by every other package.
@edge-interact/context-data-samples-js
Domain-specific type extensions — CRM (sales rep, account, deal), Healthcare (clinician, patient, clinical session), E-Commerce (customer, product, order).
@edge-interact/context-manager
Responsibilities #2–5 and #8. ContextStore (write-only), ContextQuery (read-only), ContextDispatcher (emit), ContextSubscriber (listen), IContextEnhancer pipeline.
@edge-interact/comm-manager
Responsibility #1. Bridges EdgeStream pub/sub to context-enriched messaging. Auto-enriches every published message with current user/session/conversation/entity.
@edge-interact/player-manager
Responsibility #6. UI orchestration — chat, form, workflow operations. coordinateUIs() for multi-component operations. broadcastStateChange() for cross-component sync.
@edge-interact/plugins-core
Plugin system infrastructure — IUIPlugin interface, PluginRegistry, PluginLifecycleManager (dependency resolution, health monitoring), PluginEventBus, PluginContextBuilder.
@edge-interact/built-in-plugins
Three production plugins — ChatWindowPlugin, AtlasFormsPlugin, WorkflowPlayerPlugin. Template Method pattern via BasePlugin. Complete operation sets for each UI type.
@edge-interact/client
Main client facade. EdgeInteractClientService.create(edgeStream, options). Unified API: client.state, client.players, client.ui, client.comm, client.errors, client.observability.
@edge-interact/chat-window
Vanilla JavaScript embeddable chat widget. No framework required. Named variable templates. show/hide/focus/scrollToBottom. onMessageSent/onMessageReceived events.
@edge-interact/react-hooks
React integration — EdgeInteractProvider, useEdgeInteract(), useChat(), useForm(), useWorkflow(), useSubscription(), useConnectionStatus(), useLogger().
@edge-interact/react-ui
React components — Button, Input, Card, Form, ChatWindow, Sidebar, Header. Pages — ChatPage, FormPage, DashboardPage, SettingsPage. Providers for theme, user, settings.
@edge-interact/ui
Design system — zero dependencies. 30+ color tokens per theme. 4px–48px spacing scale. Typography (h1–h6, body, caption). 5-level elevation shadows. Light/dark themes.
@edge-interact/integration
Zustand stores (conversation, message, form, settings, UI, user) + API clients (Server, Chat, Form, User, Metadata) + validators, transformers, formatters.

The context envelope — what every message carries

IContextualMessage is the complete envelope. It wraps any payload with structured context — user, session, conversation, entity, UI component, and variables.

IUserData
userIdstring
userNamestring
email?string
permissionsstring[]
attributes?Record<string, unknown>
ISessionData
sessionIdstring
startTimeISO8601 string
timezonestring
localestring
metadata?Record<string, unknown>
IConversationData
conversationIdstring
type'chat'|'form'|'workflow'|'mixed'
participantsstring[]
createdAtISO8601 string
IEntityIdentityData
type'customer'|'order'|…
idstring
displayName?string
dataRecord<string, unknown>

How a message flows through the system

Every operation follows the same 8-step pattern — from application API call to UI delivery, with full context at every stage.

1
Application calls manager API
e.g. commManager.publish({ topic: 'messages:input', body: {...} })
2
CommManager builds MessageContext
Reads current user, session, conversation, entity from ContextManager. Enriches message automatically — zero manual context passing required.
3
Message published to EdgeStream
Context-enriched IContextualMessage enters the EdgeStream pipeline with full user/session/conversation/entity attached.
4
EdgeStream hooks execute in priority order
Validation (priority 10) → Enrichment (priority 20) → NLP/business logic (priority 30) → Routing (priority 40). Each hook sees full context.
5
Message delivered to subscribers
Subscribers receive the fully-enriched, routed message. Context filter ensures each subscriber only sees messages for their conversation.
6
Context-based business logic executes
Backend handlers use context.user.permissions, context.entity.data, context.variables — no separate context lookup needed.
7
Response routed to UI component
PlayerManager delivers to the correct ChatWindow, Form, or Workflow component — using context.conversation.id for isolation.
8
Full audit log recorded
Every step logged with messageId, userId, conversationId, hook timings, and status. Complete audit trail for compliance.

Ready to eliminate context leakage?

Follow the get-started guide or see real-world patterns in examples.

Get Started See Examples