Skip to content

Erupt Atlas ​

erupt-atlas draws every @Erupt model in the live registry and the relations between them: what references what, how tightly modules are coupled, and what a change to one model would reach.

Minimum version: 2.2.0

Nothing is configured and nothing is persisted — every call rebuilds from EruptCoreService, so models registered at runtime (erupt-designer publications, erupt-flow forms) show up without a restart.

Setup ​

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-atlas</artifactId>
  <version>${erupt.version}</version>
</dependency>

The module depends on erupt-upms, erupt-tpl and erupt-data-jpa (all provided, already present in a normal project). Auto configuration adds a Model Atlas root menu (icon fa fa-diagram-project) with two entries: Model Graph and Erupt Class Registry.

Screenshots ​

Overview — every model laid out by module, with "models · cubes · relations · modules" counted along the top. Select a model and the bottom panel lists what references it and what it references under RELATIONS / FIELDS / CONFIG.

Model Atlas overview

Layers — a dependency-depth report: which foundation models the whole system stands on, and which chains the depth actually comes from.

Model Atlas layers

Seven views ​

Since 2.3.0 the tabular views — Layers, Matrix, Power, Audit — fill the full width of the screen instead of leaving margins on wide displays.

ViewWhat it shows
LineagePick a model and walk 1–5 hops in and out: what references it, and what it references
LayersA dependency-depth report: levels deep, models levelled, foundation models, longest chain. L0…Ln expand level by level, the foundation list is ranked by how many models stand on each one, and clicking any model jumps to its lineage
OverviewEvery model grouped by module, the whole structure at a glance
MatrixModule-to-module coupling heat map; the diagonal is intra-module coupling, the rest cross-module
Power@Power declarations reconciled against the function buttons the menu tree actually carries — see below
ImpactThe models a change to the selected one would reach, listed by distance
AuditWhat the graph knows but a picture does not say out loud — see below

Domain focus ​

A domain (module) bar across the top scopes the view: narrow it to a single module or keep All for the whole system. Models with no structural relation at all are called out separately and left out of the levelling. On a system with many models across many modules, this is the switch that makes the board readable again.

Power reconciliation ​

The Power view puts each model's declared permissions next to the function buttons on its menu, which is how you catch "the annotation allows it but no button was configured" and the reverse:

ColumnMeaning
Model / ModuleThe model name and the module it belongs to
Menu typeIts type in the menu tree (empty when it has no menu)
Powers onThe @Power flags that are true: add, edit, delete, query, detail, export, import, print, copy, cellEdit, ai
Menu buttonsThe function-permission buttons that actually exist in the menu tree
powerHandlerThe class name of a dynamic permission handler, when one is configured

The button side needs erupt-data-jpa

Buttons are read from the menu table. Without erupt-data-jpa there is no menu table to read, so that column comes back empty while the declaration side still renders.

Structural audit ​

The Audit view collects four kinds of structural finding:

CheckMeaning
CyclesReference loops between models — usually a sign that a dependency should be split or inverted
Shared tablesSeveral @Erupt models mapped onto the same physical table
OrphansModels nothing references, and that reference nothing
UnpublishedRegistered models that are not attached to any menu

What the graph contains ​

Node kindSource
eruptA model annotated with @Erupt
cubeAn @EruptCube semantic model (requires erupt-cube)
remoteA model served by an erupt-cloud node

Edge kinds cover reference (reference field), tab (sub-table), embed, drill, operation (row operation), cubeOf, join and table (shared table).

Used By v2.3.0+ ​

The graph only knows what fields declare: references, sub-tables and embeds are written on the model, and one pass over the annotations draws them. The other half of the picture is bound by users at runtime and lives in a configuration row that no annotation will ever mention — which form a flow is bound to, which table a menu opens, which cube a dashboard reads.

Since 2.3.0, modules report those bindings themselves through EruptUsageProvider (erupt-core, xyz.erupt.core.usage) and the atlas reads them backwards: open a model and the bottom panel gains a Used by tab listing every configuration that uses it — everything that would have to be reopened if the model changed.

Reporting moduleWhat it reports
erupt-flowThe form model a flow is bound to, and the config models of its custom nodes
erupt-upmsMenus whose type value is this model
erupt-cubeDashboards that read this cube
erupt-printPrint templates attached to this model
erupt-coreModels used as the pop-up form of a @RowOperation

A module author declares one Spring bean that implements EruptUsageProvider and returns List<EruptUsage>. EruptUsage is a record: target (the erupt name or cube name being used), type (ERUPT / CUBE), usage (what it is used as, already translated), owner (the configuration that uses it, named the way its own page names it) and route (the console route that opens that configuration, or null when it has no page of its own):

java
@Component
public class ReportUsageProvider implements EruptUsageProvider {

    @Resource
    private ReportRepository reportRepository;

    @Override
    public List<EruptUsage> usages() {
        List<EruptUsage> usages = new ArrayList<>();
        for (Report report : reportRepository.findAll()) {
            usages.add(new EruptUsage(
                    report.getErupt(),                        // the model being used
                    I18nTranslate.$translate("Report"),       // what it is used as
                    report.getTitle(),                        // which configuration uses it
                    EruptUsage.tableRoute(Report.class)       // route that opens that configuration
            ));
        }
        return usages;
    }
}

The atlas asks every provider on every request, so keep the implementation light. A provider with nothing to say, or whose tables are not there yet, returns an empty list rather than throwing — one silent module must not cost the page.

Class registry v2.2.0, moved from erupt-monitor ​

The graph is for relations, the registry for lookup: Erupt Class Registry is a table view over the same live registry, listing every @Erupt model loaded in the current process. Rows come straight from EruptCoreService, nothing is persisted, and runtime models published by erupt-designer or served by erupt-cloud nodes are listed too.

Columns:

ColumnDescription
SourceThe module / jar the model belongs to, filterable
Class Name / Display NameThe model class name and its @Erupt(name), with fuzzy search
Multi-languageWhether the model is annotated with @EruptI18n
Field CountNumber of @EruptField fields in the model
Data ProcessorThe data-source processor used (JPA, MongoDB, JDBC, etc.)
Runtime RegisteredWhether the model was registered dynamically at runtime
PublishedWhether the model has been published as a menu

Row actions:

  • Open in Atlas: jumps to the model graph with this model selected; every row of the field drill carries the same action
  • Fields (drill): every @EruptField of the model — name, title, type, edit component, required / searchable
  • Publish to Menu: publish an unpublished model as a TABLE menu, generating the full set of function-permission buttons and refreshing the menu cache
  • Model JSON: the detail view shows the complete JSON resolved from the class-level annotations

Upgrading from 2.1.x

The registry used to sit under erupt-monitor's System Monitoring menu. Existing menu rows are not moved automatically — see the upgrade guide.

APIs and permission ​

EndpointPurpose
GET /erupt-api/erupt-atlas/viewThe graph snapshot: nodes, edges and audit findings
GET /erupt-api/erupt-atlas/powerThe power reconciliation rows
GET /erupt-api/erupt-atlas/detail/{erupt}Field detail for one model, fetched when it is opened

All of them are guarded by @EruptMenuAuth("erupt-atlas.html"); grant the Model Graph menu to a role to control who may open it. The class registry is an ordinary @Erupt table menu and is granted like any other.

The graph page accepts ?erupt=<model name> to open on a given model; the registry's Open in Atlas action uses exactly that.

Model names and page text follow the console's current language: models annotated with @EruptI18n go through I18nTranslate, the rest keep their annotation text as written.

TIP

Field lists load on demand rather than riding along with the graph — for the whole registry they would dwarf it.

Contributors

The avatar of contributor named as YuePeng YuePeng

Changelog

Released under the Apache-2.0 License.