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/reactand install it withChatProvider. See Connect to OpenMax. It iscreateOpenMaxAdapter(config)handed tocreateChatHost({ adapter })from@openmaxai/chat-sdk; write the latter yourself when you want to handle expired credentials (onUnauthorized). - Another backend: write a
ChatSdkAdapter, pass it tocreateChatHost({ adapter })from@openmaxai/chat-sdk/react, and install withChatProvideras well. See Connect your own backend · Adapter API. Until the backend is ready, run the UI oncreateMemoryAdapterfrom@openmaxai/chat-sdk/testing. - Hand-written host: write
identity,messaging,inboundDelivery(usually alsoconversations) and spreadcreateLocalPorts(...)for the rest. See Connect your own backend. WithcreateChatHost({ adapter })you do not need a hand-written host for optional capabilities such asgroupManagement,cards,mentions,workItemsandagentConfig: they come from the adapter's members of the same name, andprofileCardfrom the adapter'sprofilesplusprofileCardActions. To replace only the drafts or attachments implementation you do not need a hand-written host: theportsofcreateChatHostcan replacedraftsandattachmentswhole.
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
createChatHostalready keep messages in the@openmaxai/chat-storemessage store, andCwsMessageThreadreads from it; theMessageThreadused 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.
- The adapter (
ChatSdkAdapter):identityandmessagingare required;conversations,realtime,uploadsandsessionare optional; it also carriesadapterVersion(set toCHAT_SDK_ADAPTER_VERSION) andname. It throwsChatSdkErroron failure, with one of 12 kinds such asunauthorized,networkorrate_limited. @openmaxai/chat-sdkturns the adapter into a host: identity readable synchronously, the conversation-list cache with debounced invalidation, one realtime connection per host built bycreateChatHost(opened when the first subscriber arrives), and the local capabilities ofcreateLocalPorts; messages are kept in the@openmaxai/chat-storestore. Expired credentials go through a latch: the first error whosekindisunauthorizedcallsonUnauthorizedonce, 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 throughattention. 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 with401it callsgetTokenagain 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: ifgetTokenthrew aChatSdkError, its ownkindis kept (for examplenetwork,timeoutorunavailable); a bareTypeError,TimeoutErrororAbortErrorbecomesnetwork,timeoutorcancelled; anything else (a plainError, for example) and an empty string areunauthorized. Onlyunauthorizedlatches and stops realtime reconnecting; the other kinds do not latch, and realtime keeps reconnecting.
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.
chatSdkAdapterConformancefrom@openmaxai/chat-sdk/testingruns the whole suite against your adapter. - The SDK re-exports the store hooks.
@openmaxai/chat-sdk/reactre-exportsuseMessagesanduseMessage; 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.
