HuLa-Server: a Java microservices backend built for WebSocket messaging

A backend split by function rather than by layer

HuLa-Server is an instant messaging service server described as a high performance system built on Spring Cloud, Spring Boot, Netty, MyBatis-Plus and RocketMQ, with Spring AI added on top. The project description adds SpringCloud Alibaba to that list.

The architecture is microservices organised by business capability rather than by technical layer. The README names the modules explicitly: gateway, authentication, IM, AI, ws, base, system and presence, isolated through modules declarations to keep coupling low.

Those eight names are worth expanding, because each is a separate deployable with a narrow job. luohuo-gateway is the API gateway, doing routing, JWT verification, permission checks, service discovery through Nacos, rate limiting, circuit breaking and degradation, XSS and SQL injection filtering, plus request and audit logging. luohuo-base handles tenants, organisation structure, roles with an RBAC model and application management. luohuo-oauth is the authentication service, supporting password, SMS code, email and QR code login, issuing access tokens and refresh tokens, and storing sessions in a distributed way. luohuo-im does the actual messaging, with single and group chat storage and forwarding, group management, friend relations and blacklists, and conversation lists. luohuo-presence tracks who is online. luohuo-ws owns the long connections. luohuo-system covers configuration, user administration, statistics, health monitoring and content auditing. luohuo-ai is the model integration layer.

The user is a backend team that already speaks Spring Cloud and wants a reference implementation of this particular service split, or a company that wants to adapt the modules to its own product.

The eleven step message path

The README documents the message execution path step by step, and it is the most useful part of the documentation for anyone evaluating the design.

A client sends a message to the gateway, the gateway routes it to the IM service, and the IM service persists the message. It then calls the internal PushService to distribute it. PushService queries a routing table to find the WebSocket node holding the target user, then resolves the node, device and user mapping, and dispatches directly to that node's dedicated topic. The target WebSocket node consumes the topic message, looks up its local session mapping table, and pushes to the specific client. The client returns an ACK, and the message state is updated to delivered.

Two design choices are visible here. The routing is addressed rather than broadcast: the message goes to a named topic on a named node, not to every connected client. And the ACK closes the loop, so delivery state is tracked per message rather than per connection.

The persistence step happens before the distribution step, which is the ordering you want in a messaging system. A message is durable before it is in flight, so a node failure during delivery loses the fan-out rather than the message.

The README spells the same path out step by step: a client sends a message to the gateway, the gateway routes it to the IM service, the IM service persists the message, the internal PushService handles message distribution, PushService queries the routing table to get the WS node where the target user is located, it obtains the node, device and user mapping relationship, and distributes directly to each WS node's dedicated topic. The target WS node consumes the distributed topic message, finds the local session mapping table, pushes the message to the specific client, the client returns an ACK, and the message status is updated to delivered. There is a messageFlow.png diagram in the preview/ directory of the repository that shows the same sequence.

Fingerprint mapping instead of broadcasting to every client

The performance argument in the README is about how messages are routed, and it comes with a comparison table between broadcast mode and precise routing mode.

The table claims that network message count drops from O(N) in broadcast mode to O(k) with precise routing, a stated improvement of 10 to 100 times, and that CPU consumption goes from high to low, a stated 5 to 20 times improvement, with CPU under 70 percent under high concurrency. These are the project's own figures in its own README, presented without a methodology or a workload description, so they should be read as a design claim rather than a measurement.

The mechanism behind the claim is the fingerprint mapping. The luohuo-ws module describes maintaining a fingerprint-level mapping of sessions, an automatic reconnection mechanism on failure, and intelligent message routing to the target client, with the fingerprint mapping described as the way it handles message storms. The README describes user presence as mapped at fingerprint level in the communication layer.

The idea is that a broadcast model sends every message to every node, so a cluster of N nodes does N times the work for one message. Addressed routing sends it to the node and device that own the recipient, so the cost scales with the number of recipients rather than the size of the cluster. For a deployment with many WebSocket nodes and a minority of users online at any moment, that is the difference between a linear and a constant cost.

The same module also handles calls. luohuo-ws provides WebRTC one to one audio and video calling with direct SRS connection, so the real time media path is a separate concern from the message path, which is the usual arrangement.

Spring Boot 4, Java 25 and a version mismatch in the project description

The badges at the top of the README pin the stack precisely: Spring Cloud 2025.1.2, Spring Boot 4.1.0, Netty 4.2.15.Final, MyBatis-Plus 3.5.16, RocketMQ Spring 2.3.6, Redisson 4.6.1, MySQL 8.0.30, WebSocket Reactive, Java 25 and Maven 3.9.16. Spring Cloud Alibaba 2025.1.0.0 appears in the technology stack list, where it is described as the basis for microservice governance, service discovery, the configuration centre and the gateway ecosystem.

Java 25 is described as the current compile and run baseline, with the compiler release pinned through a Maven property:

maven.compiler.release=25

One inconsistency is worth flagging before you plan a deployment. The repository description says the service is built on SpringBoot3, while the README body and the badges both say Spring Boot 4.x, with the badge naming 4.1.0. Whichever is true for the code you clone, a Spring Boot 3 to 4 jump is not a trivial upgrade for an operator, so find out which one the branch you use actually targets.

The rest of the stack is equally conventional. Redis stores user session information and message cache data, MySQL stores persistent user information and message records, Netty provides the Reactor threading model and high concurrency connection management with zero copy optimisation, and RocketMQ decouples the services, with transactional messages and ordered consumption for the IM scenario. MyBatis-Plus with Dynamic Datasource supports multi-tenant sharding.

One AI module covering many providers

luohuo-ai is the module that sets HuLa-Server apart from a plain messaging backend, and it is the reason Spring AI appears in the technology list.

The abstraction is small and readable: unified interfaces named ChatModel, ImageModel, AudioModel and VideoModel, with a factory class named AiModelFactory that dynamically creates and manages model instances for different platforms. On top of that sit unified streaming and non-streaming chat, function calling, conversation history management and context memory. Image generation supports custom sizes and styles, runs as an asynchronous task with task state tracking and file storage. Speech synthesis covers multiple voices, adjustable speed and several output formats including MP3 and WAV. Video generation submits an asynchronous task, polls status and stores the result.

The provider list is long. The Chinese platforms named include Gitee AI, SiliconFlow, Kimi, DeepSeek, Tongyi Qianwen, Wenxin Yiyan, Zhipu AI, Spark, Doubao, Hunyuan, MiniMax and Baichuan. The international list includes OpenAI, OpenRouter, Ollama, Stable Diffusion, Midjourney and Suno AI, with capability labels such as chat, image generation, audio generation and music creation attached to each.

The workflow engine is TinyFlow, integrated so that complex AI business scenarios can be orchestrated rather than called through code alone.

The honest caveat is that a unified interface does not mean uniform behaviour. Model management, quota management and usage statistics are listed as partially implemented for some AI models, which the README marks as 部分. And every one of these providers is an external service with its own billing, so the abstraction is a routing layer, not a free capability.

What the repository actually contains

The top level of the tree is short:.gitignore, LICENSE, README.en.md, README.md, docs/, luohuo-cloud/, luohuo-util/ and preview/.

That is worth pausing on. The eight modules described in the architecture section are not visible as separate directories in this repository, and there is no pom.xml at the root, no Dockerfile and no docker-compose file. The two luohuo directories that are present, luohuo-cloud and luohuo-util, suggest a parent aggregator and a shared utility module, with the service modules living in a companion repository or in an arrangement the README does not spell out for the reader working from this tree.

The consequence is that the module catalogue is a design description rather than something you can clone and build in one step from this repository alone. The README also points to a separate HuLa client project on GitHub and Gitee for the frontend, and it mirrors the repository on Gitee and GitCode as well as GitHub, which is a pattern that usually accompanies a project with a Chinese user base.

On licensing, the licence field on the repository says Apache-2.0. That is permissive, with the usual obligations to keep the licence text and the notices when you redistribute. Copying a module into a proprietary product is therefore straightforward in licence terms, though the bundled third-party dependencies of Spring, Netty, RocketMQ and the rest carry their own licences that are separate from the project's.

On maintenance, the repository is not archived and the last push was on 2026-07-04, and there are no GitHub releases, so versions are tracked by commit rather than by tag. The project also runs a WeChat community contact and a client project is maintained separately.

Editorial conclusion

HuLa-Server suits a team that wants to study or reuse a conventional Chinese enterprise instant messaging backend, with the gateway, authentication, IM, presence, WebSocket, system and AI modules separated and a per-device routing scheme rather than broadcast. It does not suit a team that wants a turnkey product with an installer, because the repository holds only the luohuo-cloud and luohuo-util trees with no build scripts at the top level, and it does not suit anyone expecting the AI module to work without picking and funding a provider. Before adopting, confirm which repository actually contains the luohuo-im and luohuo-ws modules, check the licence obligations for the Apache-2.0 code you copy, and read the message flow diagram in preview/messageFlow.png against your own gateway design.

Frequently asked questions

Official sources

1. HuLaSpark/HuLa-Server on GitHub
2. Issues
3. License: Apache-2.0
4. README