Integration Architecture
Divide responsibilities and data flow across the product service, WuKongIM cluster, and client SDK.
A reliable integration separates the product control plane from the messaging data plane. The product service decides who may do what; the WuKongIM cluster moves and stores messages in real time and in channel order.
End-user app + client SDK
-> Product service: sign in; obtain UID, device, and session settings
-> WuKongIM HTTP API: GET /route (address discovery only)
-> WuKongIM Gateway: CONNECT / SEND / RECVACK
Product service
-> WuKongIM HTTP API: trusted server-side sends and mutations
WuKongIM Gateway <-> WuKongIM cluster
-> Product webhook endpoint: async, bounded, best effort
-> Durable product queue and handlers: after receiver persistenceResponsibility split
| Component | Owns | Does not own |
|---|---|---|
| End-user app | User experience, SDK lifecycle, local state, message display | Trusted identity issuance or server authorization |
| Client SDK | Routing, connection, protocol frames, reconnect, send, receive, acknowledgements | Product accounts, group policy, or moderation |
| Product service | Login, UIDs, tokens, relationships, membership, content policy, webhook side effects | Long-lived connections or channel-log replication |
| WuKongIM cluster | Gateway, channel ordering, persistence, routing, online delivery, cluster failover | Product databases or final business rules |
Every deployment is a cluster. A one-node deployment is a single-node cluster; it does not bypass Controller, Slot, Channel, or routing semantics.
Session bootstrap
- The app authenticates with the product service through your login mechanism.
- The product service returns a stable UID, device identity, and connection settings allowed for that environment.
- The trusted backend calls
GET /routeand receivestcp_addr,ws_addr, andwss_addr. - The SDK selects an available ingress and sends CONNECT to negotiate protocol version and encryption material.
- Only after connection success does it send product messages. Connection state is not product authorization state.
Route discovery is not authentication
The current /route endpoint returns configured ingress addresses and does not validate the UID's product permissions. The ability to discover a route is not proof of authorization.
Two message entry paths
- Client path: an SDK sends over a long-lived connection and receives SENDACK, RECV, and connection-state events.
- Server path: a trusted product service calls
/message/sendfor system-originated or product-triggered messages.
Both paths converge on the same message use case and channel append path. A product service must not write node-local storage directly or bypass cluster routing because a deployment currently has one node.
Failure boundaries
- For a default persistent message, a successful SENDACK means the channel authority made a successful durable-append decision.
- Plain non-command
NoPersistreturns compatibility success without delivery; only command-styleNoPersistenters transient online delivery. Neither has a durable sequence or recovery guarantee; see Message Flags. - Online delivery, webhooks, and plugins are independent post-commit effects; conversation construction happens later during membership sync.
- A webhook failure does not turn an already-successful SENDACK into a failure.
- Client disconnect recovery uses SDK reconnect and message synchronization, not webhook replay.
For the internal commit and delivery boundaries, read Server Architecture and Message Flow. Continue with Authentication to tighten the trust boundary before implementing messaging.