erupts/erupt: annotation-driven Java admin framework with an AI harness

The problem Erupt solves: one annotated entity, one admin page

Most internal Java tools spend their first weeks on the same work: a controller per entity, a DTO layer, a search filter, pagination, Excel export, and a front-end build that nobody wants to maintain. Erupt's claim is that this scaffolding can be derived instead of written. The unit of work is a JPA entity annotated with @Erupt, and the README states the formula plainly: one class equals one admin page, with zero controllers and zero front-end build.

The audience is narrow but real. It is a Java team on Java 17 and Spring Boot 3.x that needs back-office screens for data it already models as entities. The README's own examples (user records, simple fields, choice fields) are the shape of the target: internal CRUD, not customer-facing product surfaces.

A second audience appears in the newer material. The AI skill page at skill.erupt.xyz is described as being for non-engineering roles (ops, HR, product, finance), where a person describes a system in one sentence inside Claude Code and the skill produces the entities. That is a different bet: not that you can write less Java, but that you may not need to write Java at all.

How the annotation layer becomes a UI and a REST endpoint

The mechanism is annotation processing at runtime, not code generation into your source tree. An entity carries @Erupt for page-level concerns and @EruptField for each property, and those annotations carry both the view side (what a column is titled) and the edit side (how the field is edited, whether it is searchable, whether it is required). The README's minimal example pairs @View(title = "Name") with @Edit(title = "Name", search = @Search) on a single String field.

Because the UI is rendered from those annotations at runtime, the README notes that adding a field and refreshing makes it appear. The same annotations also drive the API: the README says every @Erupt entity is a permission-aware REST endpoint. That is the important architectural consequence. There is no separate hand-written controller to keep in sync with the model, and equally no controller to inspect when something is exposed that should not be.

Page-level behaviour lives in the @Erupt annotation itself. The README's longer example attaches @Power(importable = true, export = true) for import and export, and @RowOperation with a mode and an operationHandler class for a custom row action. The handler is a Java class you supply, so custom behaviour is still Java, just attached through an annotation rather than registered in a controller.

Field widgets are selected by an EditType enum. The README shows EditType.SLIDER with a nested @SliderType(max = 90, markPoints = {0, 30, 60, 90}, dots = true), and EditType.CHOICE with a @ChoiceType whose fetchHandler is SqlChoiceFetchHandler and whose fetchHandlerParams is a SQL string such as select id, name from e_upms_menu. Choice options can therefore come from a query rather than a hard-coded list. The README lists 30+ components including date, slider, tree, code editor, reference table, autocomplete, map, signature and Markdown.

Installing Erupt and getting a first page running

There are four documented entry points. The fastest is Docker, which the README describes as an all-in-one image built on erupt-spring-boot-starter-all and containing designer, job, monitor, magic-api, notice, AI, cloud-server and an embedded H2 database, with zero configuration.

docker run -p 8080:8080 erupts/erupt
# → http://localhost:8080   login: erupt / erupt

After the container starts, open http://localhost:8080 and log in with the credentials the README gives, erupt / erupt. For production the README points at the image guide under deploy/erupt-docker/README.md and says to switch to MySQL or Redis through -e environment variables. It does not spell out those variable names in the README.

The source route runs a bundled sample against an in-memory H2 database with no configuration. The README gives the clone, the directory change, and a Maven command with -pl erupt-sample -am.

git clone https://github.com/erupts/erupt.git
cd erupt
mvn spring-boot:run -pl erupt-sample -am
# → http://localhost:8080   login: erupt / erupt

The Maven route is for adding Erupt to an existing Spring Boot application. The README says erupt-spring-boot-starter bundles what a runnable admin needs (erupt-admin plus erupt-web), while erupt-spring-boot-starter-all adds the optional modules. The version is referenced as a property rather than a fixed number.

<dependency>
    <groupId>xyz.erupt</groupId>
    <artifactId>erupt-spring-boot-starter</artifactId>
    <version>${erupt.version}</version>
</dependency>

With the dependency in place, the first real use is annotating an entity. The README's example extends BaseModel, which is where the id and audit fields come from, and marks the class with @Erupt.

@Erupt(name = "User")
@Entity
public class User extends BaseModel {

    @EruptField(
        views = @View(title = "Name"),
        edit  = @Edit(title = "Name", search = @Search)
    )
    private String name;
}

Running mvn spring-boot:run then serves the page at http://localhost:8080. The README describes the result as paged, searchable, exportable and role-gated. There is also a browser-based starter at start.erupt.xyz where modules are selected and a ready-to-run project is downloaded, and the AI skill route, which clones a skill repository into a Claude Code skills directory.

git clone https://github.com/plinian/erupt-skill.git ~/.claude/skills/erupt-admin

After that, the README says you tell Claude Code something like "Build me a CRM admin panel" and get a running system. The skill repository is a separate project from the framework itself, which matters if you are evaluating supply chain rather than features.

Where Erupt is the wrong tool

The runtime-rendering model is the source of most of the limitations. If your admin screens need interaction the annotation set does not describe, you are not extending a UI, you are working around a generator. The README lists 30+ components and an EditType enum, which is a fixed vocabulary. Anything outside it means custom Java through a handler, or a separate front-end, at which point you have two systems.

The default credentials are a real operational concern. Every quickstart path in the README ends at http://localhost:8080 with erupt / erupt, and the Docker image ships with embedded H2 and no configuration. That is excellent for a first run and unacceptable as a deployment. The README points to the Docker image guide for switching to MySQL or Redis but does not document a hardening checklist in the main file.

Database support is broad but bounded: MySQL, PostgreSQL, Oracle, SQL Server and DM through JPA, with MongoDB handled by a separate erupt-mongodb module. If your data lives somewhere else, the framework does not reach it.

There is also a licensing boundary inside the feature set. The README separates the open modules from commercial Chart, Flow, Tenant and Cube modules covering reporting, workflow, SaaS and BI. A team that reads the feature list as a single product will discover the split late. Finally, the README does not document a rollback or downgrade path between the 2.x releases, so upgrade behaviour is something to establish yourself rather than assume.

Erupt compared with Spring Data REST and a hand-written admin

The closest comparison is Spring Data REST, which also exposes JPA repositories as HTTP endpoints without controllers. The difference is where the metadata lives. Spring Data REST infers an API surface from repository interfaces and leaves the UI to you. Erupt infers both the API and the admin UI from annotations on the entity, and adds page-level concerns (import, export, row operations, RBAC) that Spring Data REST does not attempt.

The second alternative is simply writing the admin: a controller per entity plus a front-end. You get total control and a codebase that any Java developer can read without knowing Erupt's annotation vocabulary. You also pay for every screen twice, once in the API and once in the UI, and you maintain the front-end build the README treats as the thing to eliminate.

A third comparison is the AI route against the framework route. The README claims the skill costs roughly one twentieth the tokens of writing from scratch, because only entities get written and the UI and APIs render from annotations at runtime. That claim is about generation cost, not runtime cost, and it does not change what runs in production: the same framework either way.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-20, which is recent. Releases are frequent: 2.1.1 on 2026-08-30, 2.1.0 on 2026-08-23, and 2.0.4 on 2026-07-19. Frequent minor releases mean the upgrade surface is real. The README does not document a rollback path between 2.x versions, and the CHANGELOG.md at the repository root is where release-to-release changes would be tracked.

Licensing is Apache-2.0, which is permissive and generally suitable for commercial internal tools. The boundary to watch is not the licence file but the module split: Chart, Flow, Tenant and Cube are described as commercial modules. Apache-2.0 on the core does not extend to those. This is a factual boundary, not legal advice; if the commercial modules matter to your plans, the terms are a separate question from the licence badge.

The upgrade cost is concentrated in annotations, which is both good and bad. Annotation changes are visible in a diff and compile-time, so breakage tends to surface early. Runtime behaviour that depends on annotation interpretation, such as how a search field or a choice fetch handler is resolved, will not surface until the page renders. The README does not describe a compatibility policy across minor versions.

Editorial conclusion

Adopt Erupt if you already run Java 17 and Spring Boot 3.x and your internal tools are mostly CRUD over JPA entities: the annotation layer removes controller and front-end work, and the Docker image gets you to a running admin on port 8080 with no configuration. Do not adopt it if your admin UI needs bespoke interaction design, or if you cannot accept that the UI and REST endpoints are generated from annotations at runtime rather than written as code you control. Before committing, verify three things: that your database is on the supported list (MySQL, PostgreSQL, Oracle, SQL Server, DM, with MongoDB behind erupt-mongodb), that the Apache-2.0 licensed modules cover what you need rather than the commercial Chart, Flow, Tenant and Cube modules, and that the default erupt/erupt login and H2 setup are replaced before anything is exposed beyond localhost.

Frequently asked questions

Official sources

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