Ballcat splits an admin platform into Maven modules

A component set, not a framework

The project describes itself as a scaffold for quickly building enterprise admin systems, with starters for extending it. What arrives in Maven Central is a set of artifacts, and the repository root makes the decomposition plain: `security/`, `datascope/`, `operation-log/`, `xss/`, `idempotent/`, `i18n/`, `job/`, `excel/`, `mail/`, `sms/`, `pay/`, `oss/`, `redis/`, `kafka/`, `grpc/`, `openapi/`, `websocket/`, `mybatis-plus/`, `file/`, `ip/`, `ntp/`, `dingtalk/`, `tesseract/`, `fieldcrypt/` and `desensitize/`, alongside `common/` and `web/`.

Three more directories at the root are build infrastructure rather than features: `ballcat-parent/`, `ballcat-dependencies/` for managed versions, and `ballcat-checkstyle/` for the code style rules, with a matching `.springjavaformatconfig` file. There is also an `api-signature/` directory and an `api-signature` concern that reappears in the repository layout, which is the pattern for keeping public method signatures stable across versions.

The result is that you adopt capabilities, not a framework. A project wanting only data-scope filtering pulls `datascope` and leaves the other modules alone. That is a genuinely different model from the all-or-nothing quickstart templates that dominate this category, and it is the main reason to look at this project at all.

The feature list maps onto real admin requirements

The description enumerates what the scaffold covers, and the names are more informative than they first appear.

Separation of front-end and back-end users means two distinct account domains rather than one table with a role column, which is the pattern most multi-tenant admin systems in China require. Menu permissions and data permissions are different problems, and the repository has a `datascope/` module for the second one, alongside `security/` for authentication and authorisation.

The observability set is split into three modules by intent rather than lumped together: access logs, operation logs and exception logs, with `operation-log/` as its own artifact. Logging who changed which row is the feature teams discover they needed six months after launch.

The defensive modules are the interesting ones for a reviewer. `xss/` handles XSS filtering, and the description names SQL injection prevention as well. `desensitize/` covers data masking for sensitive fields and `fieldcrypt/` covers field-level encryption, which are different requirements that often get conflated into one vague word in a specification. `idempotent/` is there for duplicate request handling, and `tesseract/` for OCR, which suggests document handling was a real use case rather than a listed intention.

Internationalisation is a first-class module in `i18n/`, alongside `ntp/` for time synchronisation, which matters more than it sounds for audit logs that must be comparable across servers.

Where to get it, and the snapshot caveat

The README states that all JAR artifacts have been pushed to the Maven central repository, and that a detailed changelog is listed for each version upgrade. So installation is a matter of adding the artifacts you want as Maven dependencies and resolving them normally.

If you want the SNAPSHOT builds instead, the README gives a specific repository configuration to add to your pom.xml:

<repositories>
  <repository>
    <name>Central Portal Snapshots</name>
    <id>central-portal-snapshots</id>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Documentation is split by version, with a 1.x site at v1.ballcat.cn and a 2.x site at v2.ballcat.cn, and the repository is mirrored across GitHub, Gitee and GitCode.

The companion repositories are where the actual application lives. `ballcat-boot` is the admin server template, `ballcat-codegen` is the code generator, `ballcat-business` holds common business modules, and there are three front ends: `ballcat-ui-react`, `ballcat-admin-ui-vue3` and `ballcat-ui-vue` for Vue 2. `ballcat-samples` holds usage examples for the components. The starter repositories list is the practical selection surface, since picking a scaffold means picking a front end and a server template.

master is 2.x and 2.x is not finished

The most important line in the README is a warning at the top of the page: the master branch is version 2.x and is still in development, and anyone who wants 1.x should switch to the 1.x branch.

That single statement changes how you should read the repository. A default checkout is a work in progress, and the documentation split between v1 and v2 sites is a symptom of the same thing. Anyone evaluating this project needs to choose a branch before reading anything else, and an evaluator who only looks at master will form the wrong impression of both the API surface and the documentation state.

The release history makes the gap visible. Versions 1.4.1 on 2023-10-24, 1.4.2 on 2024-04-13 and 1.4.3 on 2026-07-30 show a project that ships infrequently, with a two-year gap before the most recent tag. That 1.4.3 tag was published on 2026-07-30, the same date as the last push, so the current line of work is the 2.x development and the 1.x line may or may not continue.

The cadence is the thing to weigh against your roadmap. A scaffold you adopt is a scaffold you own from that version forward, and a project with multi-month gaps between patch releases means you are reading changelogs rather than release notes.

Frontend coupling and licensing

Two structural points before you commit.

First, the module boundaries assume a particular stack. `mybatis-plus/` as a module means the data access layer is built on MyBatis-Plus, and the presence of `datascope/` and `security/` implies conventions about how queries and authentication are wired. If your project already has its own persistence and security layers, the modules you actually want are the smaller ones like `desensitize/`, `fieldcrypt/` and `xss/`, and the benefit shrinks accordingly. The value is highest when you adopt the whole starter.

Second, the front ends are separate projects. Three of them exist, covering React, Vue 3 and Vue 2, which means features will not land in all three at once. Choosing a starter is choosing which front end you will be tracking.

On licensing, the project is Apache 2.0 with `LICENSE.txt` at the root and a copyright line for the Ballcat authors. That is permissive and does not impose the reciprocal obligations you get with a copyleft admin template, which matters because you will be copying code out of these modules into a proprietary application.

The API signature directory is the other governance signal worth noting. For a library set, freezing public signatures is what stops an innocuous minor version from breaking your build months later, and the presence of that directory suggests the project treats it as a problem worth solving.

Editorial conclusion

Adopt Ballcat for an internal admin system on Spring Boot where menu and data permissions, operation logging and XSS filtering are all needed, and pin to a 1.x release since master is an in-development 2.x line. Do not adopt it if you need a single dependency to reason about, because each capability is its own artifact with its own upgrade path. Verify first which branch you are on, read CHANGELOG.md for the jump from 1.4.2 to 1.4.3 dated 2026-07-30, and note that the last push was also on 2026-07-30, so 2.x has no release you can depend on yet.

Frequently asked questions

Official sources

1. ballcat-projects/ballcat on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases