# MateCloud: one codebase that grows into microservices instead of being rewritten

> A Spring Boot 4 DDD scaffold whose headline feature is a single configuration flag that decides whether the whole system runs as one JVM or as a Dubbo service cluster.

**mateaix/matecloud** — MateCloud is a microservices architecture based on Spring Cloud Alibaba. It currently integrates Spring Boot 4.0.8, Spring Cloud 2025, Spring Cloud Alibaba 2025, Spring AI 2.0.1, Spring Security OAuth2, Feign, Dubbo, JetCache, RocketMQ and more, as a multi-tenant low-code platform and SaaS development kit.

- Repository: https://github.com/mateaix/matecloud
- Website: https://mate.vip
- Stars: 1,699 · Forks: 477
- Language: Java
- License: Apache-2.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/mateaix-matecloud

## What the project actually ships

MateCloud describes itself as an AI-native, cloud-native DDD microservice scaffold built on Spring Boot 4, Spring Cloud 2025, Dubbo 3 and Spring AI 2.0.1. The repository is Apache-2.0 licensed, written in Java, sits at roughly 1,700 stars and 477 forks with 17 open issues, and was last pushed on 2026-09-19. The default branch is dev rather than main, which tells you something about how releases are cut.

The open-source scope is narrower than the marketing. The README states that the community edition contains four core services, a gateway plus auth, system and notice, alongside a set of ready-to-use starters. The feature table goes further and describes a low-code style platform, which is the vocabulary of the project's commercial tier rather than something to expect from the public repository.

The README itself is written in Chinese, and the documentation site ships as a separate VitePress application under `mate-ui/apps/docs`. That matters if you are evaluating the project from outside a Chinese-speaking team: the code, the API surface and the release notes are all usable, but the prose explaining the design intent is Chinese-only. The architecture document it links as the overall architecture reference is also hosted in that same docs application, so the real explanation of the layering lives there rather than in the repository.

## The dual-mode switch is the actual product

The 5.0.8 release, published in late June 2026, is the reason to look at this project now. Its premise is that choosing between a monolith and microservices used to be an irreversible architectural decision, and the release makes it a configuration choice instead. One property, `mate.rpc.mode`, selects `local` for a single-JAR deployment or `dubbo` for the distributed form.

The release notes are unusually specific about the mechanism, and that specificity is what makes the claim assessable. Business modules are packaged twice, as a thin library consumed by the monolith and as a runnable fat jar for service deployment. Interfaces that differ between the two modes, such as a role permission resolver port and a Sa-Token token issuer, are extracted behind ports so both forms share one implementation. Domain events are dispatched through Spring events inside the monolith and automatically switch to Dubbo broadcast once the service is split. Flyway is described as adopting an already existing schema on first monolith startup rather than recreating it, and all monolith-specific differences are collected into a single `mate-infra-local.yml` so the main configuration file stays clean.

The user-visible promise is that the frontend needs no changes and the database needs no migration when you move between forms, and that the monolith listens on port 9010, the same port as the gateway in distributed mode. The full design write-up lives in the repository at `docs/rfcs/045-monolith-microservice-dual-mode.md`, which is the first file to read if you intend to rely on this. A single flag only works if the abstractions below it are genuinely shared, and the RFC is where you can see whether they are.

## Starter modules, and a count that does not add up

The capability layer is the actual body of the repository, and the module listing is more informative than the summary numbers. `mate-common` splits into `mate-base`, holding the base entity, result wrapper, business exception and error code, and `mate-api`, holding RPC interfaces, commands and responses. `mate-starters` covers persistence with MyBatis Plus, Druid and Flyway, web with global exception handling and Jackson, a two-level cache combining Caffeine and Redis, Nacos registration and configuration, Dubbo RPC, Sa-Token for servlet and reactive stacks, monitoring through Actuator and Prometheus, RabbitMQ with delayed queues, an XXL-Job executor, a security starter, MinIO file handling, Excel import and export through EasyExcel, and multi-tenancy. `mate-starters-contrib` adds distributed transactions through Seata, sharding through ShardingSphere, Sentinel rate limiting, gray release, a lightweight workflow engine and an Aviator rule engine.

Here is a documentation problem worth naming. The opening description advertises 27 ready-to-use starters split as 18 core and 9 advanced, and the feature table repeats the 27 figure. The module description instead counts `mate-starters` as 13, split 7 core and 6 business, and `mate-starters-contrib` as 8 advanced, which totals 21. Both numbers appear in the same README. The tree is the more reliable source, and anyone building a business case on the starter count should count directories rather than trusting either figure.

## Layering, annotations, tenancy and gray release

The four-layer DDD split is trigger, application, domain and infrastructure, with the README claiming the domain layer carries no framework dependencies. Read and write separation is expressed through paired command and query services rather than through a CQRS framework, which is the lightweight interpretation of that pattern.

Cross-cutting behavior is delivered as annotations rather than as advice in a style guide. There is a distributed lock backed by Redisson, an API signature annotation using HMAC-SHA256 to detect tampering, a rate limit annotation backed by Sentinel dynamic rules, an audit log annotation, a data permission annotation that filters rows declaratively, and an idempotency annotation against duplicate submission. That set is a good signal about what the authors consider the tedious parts of enterprise Java, and it is the kind of thing teams otherwise rebuild badly.

Multi-tenancy offers three isolation strategies, row level, schema level and a dedicated data source per tenant, which is the honest way to present a problem that has no free answer. Gray release is handled on both the Dubbo and the gateway path. Code generation from the CLI produces the four layers plus a Flyway migration, which is a reasonable way to make the layering stick.

One design note is worth repeating because it is easy to miss: each service keeps its own version history table named `flyway_history_<module>`, and first startup of `mate-system` runs migrations from `db/migration/` to create tables and seed the built-in administrator, roles, menus and dictionaries. Nothing needs to be created by hand.

## AI and MCP as a working loop

The project treats model integration as part of the platform rather than as a side project. Spring AI 2.0.1 provides the abstraction, annotations are discovered automatically as tools, and the integration adds conversation memory and streaming responses. Anthropic, OpenAI, DeepSeek and Ollama are described as native providers, with Zhipu and MiniMax reachable through compatible endpoints.

The more interesting half is the MCP server. The CLI exposes itself and the business tool annotations as Model Context Protocol tools, which is positioned as a closed loop of observation, reasoning, execution and feedback: an agent can inspect services, make RPC calls, generate code and run database migrations against a running cluster. The README names both `mate-cli --mcp` and `mate --mcp` as entry points and lists Claude Code and Claude Desktop as consumers.

This is worth reading carefully rather than skimming. MCP exposure of internal tools is a powerful idea and also an authorization question, and a scaffold that wires business RPC and schema migration into an agent's toolset needs an explicit answer about who can invoke what. The README does not discuss that boundary, so treat it as something to design yourself.

## Running it locally

The quick start is short and depends on JDK 21, Maven 3.9, Docker with Compose, and Node 20 for the frontend. The four steps below are the sequence the README gives, in order.

```bash
mvn clean install -DskipTests
make infra-up
java -jar mate-cli/target/mate-cli.jar config init
make up
```

Infrastructure comes up first, covering MySQL, Redis, RabbitMQ, Nacos and MinIO, and the Makefile target spells out the services it touches:

```
infra-up:
	docker-compose up -d mysql redis rabbitmq nacos minio
```

After startup the backend is reached through gateway port 9010 and the Nacos console sits on 8848. The frontend is a pnpm monorepo with the admin application on port 3000 and the documentation site on 5174, and the development credentials are the unremarkable `admin` and `admin123`. Nothing about that default pair is a criticism of a local scaffold, but it is a reminder that the seeded administrator should be rotated before this runs anywhere reachable.

The Dockerfile is also worth reading if you plan to deploy rather than demo. It is a two-stage Alpine build using Maven with Temurin 21 for compilation and a JRE-only runtime image, it prefers a runnable exec jar when a module produces both a thin and a fat artifact, and it runs as a non-root user with a writable home directory for package manager caches. The heap defaults to 512 megabytes with G1 garbage collection enabled.

## Infrastructure defaults you should change

The Compose file is a reasonable picture of what the platform expects. MySQL 8.0 runs with utf8mb4 and its own collations, Redis is a 7-alpine image with a required password, RabbitMQ is the management-tagged 3.13 image, and the Nacos server is pinned:

```
image: nacos/nacos-server:v3.2.1
```

Nacos runs standalone with authentication enabled, and the environment example explains a requirement that catches people out: on Nacos 3.x an auth token must be set, and its value is a Base64 string that decodes to at least 32 characters. The same file walks through creating the initial Nacos administrator through the admin API and explains that the server identity key is a trusted-identity header whose value lets a caller bypass user authentication entirely. The shipped example sets that value to the literal word security, and the comment above it says plainly that production must use a strong random string instead. That warning is easy to skim past and it is the most consequential line in the file.

The remaining defaults follow the same pattern. Database, cache and broker credentials all share the project name as their value, the XXL-Job access token is a readable string, and MinIO keys are in the same family. Treat `.env.example` as a template to fill in, not as a starting configuration to keep.

## Version numbers and a release history with a gap

Two things in the metadata deserve scrutiny before you plan a migration.

The first is a patch-level disagreement inside the Spring Boot version. The badge at the top of the README reads Spring Boot 4.0.7, and the 5.0.8 release notes repeat 4.0.7. The dependency table in the same README lists 4.0.8, and so does the repository description. Since patch releases of a framework commonly carry security fixes, pick the version from your own dependency resolution rather than from either document, and check the changelog if the difference matters to you.

The second is the release history. There are three tagged releases, and two of them, 4.3.8 and 4.4.8, were published within about an hour of each other on 2022-04-29. Both belong to the Spring Boot 2.6 generation, with Spring Cloud 2021, Nacos 2.0.4 and Vue 3.2. The third release is 5.0.8 from 2026-06-28, which lands on Spring Boot 4 and Spring Cloud 2025. Nothing is tagged between those points, so the public release history shows a four-year jump rather than a gradual climb.

That gap is not proof of inactivity. The commit history between those tags is not visible from tags alone, the repository was pushed to in September 2026, and the presence of AGENTS.md, CLAUDE.md and a CONTRIBUTING file suggests active development. What it does mean is that the two 2022 tags tell you nothing about the current architecture, and older tutorials built on them describe a different framework generation entirely. Judge the project from the 5.0.8 notes and the current tree.

## Where this fits

The clearest fit is a team that has decided it wants a Java service backbone with the standard enterprise capabilities already present, and is still early enough that the monolith form is a legitimate target rather than a retreat. Starting in the monolith form gives you one jar, no registry and no broker, and the claim that you can later split is at least documented with a design document rather than a slogan.

The cases to think carefully about are the ones the repository does not address. Data permission filtering, gray release routing and Sentinel rules are the sort of features that need to be exercised against real traffic shapes, and a scaffold is a starting point for validating them rather than evidence they work. The AI and MCP integration is the most novel part and the least documented in terms of safety, since agent access to RPC and migrations is granted without a stated authorization model.

There is also an ecosystem signal worth weighing. The homepage points to a paid community, the open-source edition is deliberately scoped, and the maintained default branch is dev. None of that is disqualifying for a scaffold whose commercial model is support and hosted tooling, but it does mean you are evaluating an open-source subset of a product rather than the product itself. Read the release notes, the RFC on dual mode and the dependency table, and treat the marketing counts with suspicion. Everything that matters structurally is verifiable in the repository.

## Conclusion

MateCloud is unusual among Chinese framework scaffolds in treating deployment shape as a configuration problem rather than an architectural fork, and the release notes for 5.0.8 lay out the mechanism honestly enough to evaluate: dual packaging, port and adapter extraction, in-process domain events, and schema adoption rather than recreation. That is a real engineering answer to a real pain. What the repository does not settle is how much of the promise is production-proven, since the only tagged releases jump from April 2022 straight to June 2026, the default branch is dev, and the README and dependency table disagree about the Spring Boot patch level. For most evaluators the practical entry point is to build the monolith form first, because that is the mode with no infrastructure dependencies, and to read docs/rfcs/045 before assuming the microservice mode has the same parity.

## FAQ

### What is MateCloud?

It is an Apache-2.0 licensed Java scaffold for DDD microservices built on Spring Boot 4, Spring Cloud 2025, Dubbo 3 and Spring AI 2.0.1. The open-source edition includes a gateway, auth, system and notice services, a set of ready-to-use starters for caching, locking, messaging, tenancy, security and observability, and a Vue 3 admin frontend served as a pnpm monorepo.

### How do you switch between monolith and microservices?

A single configuration property named `mate.rpc.mode` chooses between `local` for a single-JAR deployment and `dubbo` for the distributed form. The 5.0.8 release notes describe the supporting mechanics: modules are packaged as both a thin library and a runnable fat jar, mode-dependent interfaces are extracted behind ports, domain events switch between Spring events and Dubbo broadcast, and Flyway adopts an existing schema rather than recreating it. The full design is written up in `docs/rfcs/045-monolith-microservice-dual-mode.md`.

### How do I run MateCloud locally?

You need JDK 21, Maven 3.9, Docker with Compose and Node 20. From the repository root, run a full build, start the infrastructure targets, initialize Nacos configuration with the CLI jar and its `config init` command, then start the services. The backend is reached through gateway port 9010, Nacos is on 8848, the admin frontend runs on 3000, and the seeded development credentials are admin and admin123.

### How many starters does MateCloud include?

The README is inconsistent. The opening description and the feature table both advertise 27 ready-to-use starters split as 18 core and 9 advanced, while the module breakdown in the same file counts 13 in `mate-starters` plus 8 in `mate-starters-contrib`, which totals 21. Counting the starter directories in the tree is the more reliable approach.

## Sources

- [License: Apache-2.0](https://github.com/mateaix/matecloud/blob/dev/LICENSE)
- [mateaix/matecloud on GitHub](https://github.com/mateaix/matecloud)
- [Project website](https://mate.vip)
- [README](https://github.com/mateaix/matecloud/blob/dev/README.md)
- [Releases](https://github.com/mateaix/matecloud/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mateaix-matecloud