OpenMax
Free Trial

Architecture overview

How the chat UI, the SDK, adapters and your app fit together — layers, packages and entry points, how a host is wired, and the adapter interface between the SDK and a backend.

Architecture overview

The UI only draws. Fetching data, the realtime connection, toasts and drafts belong to a host object that you install once at the top; every component reads its capabilities from it.

Layers

Layer Package What it does
UI @openmaxai/chat Conversation list, message thread, composer, header, group management, floating / docked surfaces, and the ChatHost contract (@openmaxai/chat/host). Never calls fetch, a router or window.
Host and shared layer @openmaxai/chat-sdk Backend-agnostic: createChatHost({ adapter }) builds a host from an adapter; the adapter interface ChatSdkAdapter, the unified error ChatSdkError and the expired-credentials callback onUnauthorized; createLocalPorts(...) provides the backend-independent capabilities (drafts, attachments and the upload task board, text rendering, attention, strings, instance scope).
Backend adapter @openmaxai/chat-openmax createOpenMaxAdapter(config) connects to OpenMax REST, realtime and uploads; createChatHost(config) from @openmaxai/chat-openmax/react does it in one line.
Data @openmaxai/chat-store Message store, thread loader, gap-fill, request cache and local storage ChatStorage; @openmaxai/chat-store/react holds the hooks that read the store.
Foundation @openmaxai/chat-internals (installed as a dependency of the packages above; do not import it) Styled primitives and theme CSS variables; English and Chinese strings; the OpenMax REST client, gateway types and realtime frame decoding.

The other pages in this section follow the data downwards:

Page What it covers
Capabilities Which fields a host has, and what happens when one is missing
Realtime and sync How server changes reach the client, and how gaps are filled after a disconnect or a missed frame
Quality (not published yet) The target design for layering, data flow, performance, availability and stability; parts not implemented yet are marked "Planned"

Packages and entry points

Package Role Depends on
@openmaxai/chat UI components and the host contract ChatHost @openmaxai/chat-store, @openmaxai/chat-internals; peers react 19, @tanstack/react-query 5 (optional, used only by the legacy message thread @openmaxai/chat/message-thread)
@openmaxai/chat-sdk Backend-agnostic host: the adapter interface, createChatHost({ adapter }), local capabilities that hand-written hosts can use too, the error model, an in-memory adapter for tests @openmaxai/chat, @openmaxai/chat-store (exact version), @openmaxai/chat-internals; same peers
@openmaxai/chat-openmax The OpenMax adapter createOpenMaxAdapter and the one-line entry createChatHost(config) @openmaxai/chat-internals; peers @openmaxai/chat, @openmaxai/chat-sdk and @openmaxai/chat-store (exact version), plus the same peers
@openmaxai/chat-store The message store and the hooks that read it; see @openmaxai/chat-store No other chat package; peer react 19 (optional)
@openmaxai/chat-internals Internal building blocks shared by the packages above: styled primitives and theme CSS variables, English and Chinese strings, the OpenMax REST client, gateway types and realtime frame decoding. Installed with them; not a public API, do not import it No other chat package; peers react, react-dom 19

The "Depends on" column follows dependencies and peerDependencies in each package.json, listing the chat packages and peers only, not third-party dependencies. All of them are released together under one version; see Known limitations · Packaging. The debug panel ships inside @openmaxai/chat-sdk and is used through @openmaxai/chat-sdk/devtools; see Devtools.

@openmaxai/chat has one entry per area of the UI: /host, /conversation-list, /message-thread, /composer, /header, /group-management, /surfaces; the root @openmaxai/chat re-exports the common parts. @openmaxai/chat-sdk has four public entries: the React-free root @openmaxai/chat-sdk (the adapter interface, ChatSdkError, config and storage types), @openmaxai/chat-sdk/react (createChatHost, ChatProvider, ConversationScope, createLocalPorts and more), @openmaxai/chat-sdk/testing (createMemoryAdapter) and @openmaxai/chat-sdk/devtools (the debug panel). @openmaxai/chat-openmax has a root entry (createOpenMaxAdapter) and @openmaxai/chat-openmax/react (createChatHost(config), which also re-exports ChatProvider, ConversationScope and the conversation-list hook, so an OpenMax app imports from this one entry). Every export is listed in @openmaxai/chat, @openmaxai/chat-sdk, @openmaxai/chat-openmax and @openmaxai/chat-store.

Wiring a host

  • OpenMax: build the host with createChatHost(config) from @openmaxai/chat-openmax/react and install it with ChatProvider. See Connect to OpenMax. It is createOpenMaxAdapter(config) handed to createChatHost({ adapter }) from @openmaxai/chat-sdk; write the latter yourself when you want to handle expired credentials (onUnauthorized).
  • Another backend: write a ChatSdkAdapter, pass it to createChatHost({ adapter }) from @openmaxai/chat-sdk/react, and install with ChatProvider as well. See Connect your own backend · Adapter API. Until the backend is ready, run the UI on createMemoryAdapter from @openmaxai/chat-sdk/testing.
  • Hand-written host: write identity, messaging, inboundDelivery (usually also conversations) and spread createLocalPorts(...) for the rest. See Connect your own backend. With createChatHost({ adapter }) you do not need a hand-written host for optional capabilities such as groupManagement, cards, mentions, workItems and agentConfig: they come from the adapter's members of the same name, and profileCard from the adapter's profiles plus profileCardActions. To replace only the drafts or attachments implementation you do not need a hand-written host: the ports of createChatHost can replace drafts and attachments whole.

The components and the install entry point are the same all three ways. Planned

Design principles

  • The UI never calls a backend. Swapping the backend, or using an in-memory mock, needs no component changes. The demos on this site run on such a mock.
  • One feature, one capability. A host that leaves out an optional capability loses only that feature. See Capabilities.
  • Hard state is written once. Optimistic sending, gap-fill after a disconnect, the message cache, drafts and the upload task board live in the library, not in each host. Hosts built by createChatHost already keep messages in the @openmaxai/chat-store message store, and CwsMessageThread reads from it; the MessageThread used by hand-written hosts does not read from the store yet, and agent runs are not kept there yet. Those two parts are still planned.
  • People and agents share one path. An agent is a conversation member and its reply is an ordinary message; run progress travels on the same realtime connection and follows the conversation's visibility rules.

Between the SDK and a backend: adapters

@openmaxai/chat-sdk is backend-agnostic: it builds a host from an adapter object (createChatHost({ adapter })), and @openmaxai/chat-openmax is the first adapter. Components only know the ChatHost contract, not which adapter is behind it. The full adapter interface is in Adapter interface, unified errors are in Error model, and the hooks app code uses to read the store are in React binding.

Architecture: UI, SDK and adapters
Arrows point to the layer that uses or is fed by the box; adapters talk to their backend over the network. Red: the only OpenMax-specific package.
  • The adapter (ChatSdkAdapter): identity and messaging are required; conversations, realtime, uploads and session are optional; it also carries adapterVersion (set to CHAT_SDK_ADAPTER_VERSION) and name. It throws ChatSdkError on failure, with one of 12 kinds such as unauthorized, network or rate_limited.
  • @openmaxai/chat-sdk turns the adapter into a host: identity readable synchronously, the conversation-list cache with debounced invalidation, one realtime connection per host built by createChatHost (opened when the first subscriber arrives), and the local capabilities of createLocalPorts; messages are kept in the @openmaxai/chat-store store. Expired credentials go through a latch: the first error whose kind is unauthorized calls onUnauthorized once, further failures while latched do not, and a success of a call started after latching releases it; without a callback the SDK shows one notice through attention. That realtime connection is not shared with any connection the app already has: an app that keeps its own connection to the same backend has two open.
  • @openmaxai/chat-openmax: createOpenMaxAdapter(config) connects to OpenMax REST, realtime (a one-time ticket first, then the WebSocket; frames decoded inside the adapter) and uploads. When a request is rejected with 401 it calls getToken again with { refresh: true } (requests rejected at the same time share that one refresh) and re-sends the request once. When no token comes back, the cause decides the kind: if getToken threw a ChatSdkError, its own kind is kept (for example network, timeout or unavailable); a bare TypeError, TimeoutError or AbortError becomes network, timeout or cancelled; anything else (a plain Error, for example) and an empty string are unauthorized. Only unauthorized latches and stops realtime reconnecting; the other kinds do not latch, and realtime keeps reconnecting.
Package dependency graph
Arrows point from a package to what it depends on (dependencies and peerDependencies in package.json). @openmaxai/chat-internals holds the shared internal building blocks and is installed with the other packages; do not import it. @openmaxai/chat-sdk depends on neither @openmaxai/chat-openmax nor the OpenMax REST client, and a package test checks that. @openmaxai/chat-store depends on no other chat package. The two app boxes at the top show only the entry each kind of app starts from.

Dependencies point one way: @openmaxai/chat-openmax → @openmaxai/chat-sdk → @openmaxai/chat → @openmaxai/chat-store. @openmaxai/chat-sdk also depends on @openmaxai/chat-store directly, and its root entry re-exports the storage interface ChatStorage with createMemoryStorage and createIndexedDbStorage. @openmaxai/chat-store depends on no other chat package. @openmaxai/chat-sdk itself uses neither the OpenMax REST client nor @openmaxai/chat-openmax, and a package test guards that. The shared internal building blocks ship in @openmaxai/chat-internals: @openmaxai/chat uses it for the Agent run frame definitions (which bring in @bufbuild/protobuf), and @openmaxai/chat-openmax for the OpenMax REST client and realtime frame decoding.

Still planned

Planned

  • Conformance tests. chatSdkAdapterConformance from @openmaxai/chat-sdk/testing runs the whole suite against your adapter.
  • The SDK re-exports the store hooks. @openmaxai/chat-sdk/react re-exports useMessages and useMessage; today they are imported from @openmaxai/chat-store/react.
  • Agent run components in a new entry, @openmaxai/chat/agent-runs.
  • The remaining adapter members and the rest of the error model: fetching one member who is not in the member lists, a backend-computed unread total, and the error handling listed in Errors · Not done yet.