From f7535f51e9fa324b46992806e30bb88287995c95 Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:10:14 +0300 Subject: [PATCH 1/3] Add CLAUDE.md with build commands and architecture guidance Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d403d1d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,80 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +Hyperion is a codbex Edition product for **BPMN business-process modeling, management and operation**, built on the [Eclipse Dirigible](https://www.dirigible.io) low-code platform (Flowable as the BPM engine) packaged as a Spring Boot application. The repo itself contains very little business logic — it is primarily an **assembly**: it wires together a curated set of Dirigible component artifacts via Maven dependencies, adds branding, and overrides a few UI pieces. Understanding the architecture means understanding *what is assembled and how it is overridden*, not a large local codebase. + +Requires **JDK 21**. Default login is `admin` / `admin`; the app serves on port **80**. + +## Build & run + +All commands run from the repo root. + +```shell +# Fast build (skips tests/checks) — produces application/target/codbex-hyperion-*.jar +mvn -T 1C clean install -P quick-build + +# Run the standalone jar (the --add-opens flags are required) +java \ + --add-opens=java.base/java.lang=ALL-UNNAMED \ + --add-opens=java.base/java.lang.reflect=ALL-UNNAMED \ + --add-opens=java.base/java.nio=ALL-UNNAMED \ + -jar application/target/codbex-hyperion-*.jar +# add -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 to debug + +# Docker (after a build): from application/ +docker build . --tag ghcr.io/codbex/codbex-hyperion:latest +``` + +Access after start: app at , Swagger UI at . + +### Tests + +```shell +mvn clean install -P unit-tests # unit tests only +mvn clean install -P integration-tests # integration tests (*IT, Selenium-based UI tests) +mvn clean install -P tests # everything +``` + +Run a single test with the standard Surefire/Failsafe selector, e.g.: +```shell +mvn test -P unit-tests -Dtest=HyperionApplicationTest +mvn verify -P integration-tests -Dit.test=HomePageIT +``` + +### Formatting + +```shell +mvn verify -P format # applies the codbex code formatter +``` +Code style is enforced by the parent `com.codbex.platform:codbex-platform-parent` POM. Run this before committing Java changes. + +## Module layout + +Maven multi-module project (`pom.xml` lists the modules). Parent is `codbex-platform-parent`, which supplies dependency versions, the build profiles above, and the formatter — so this repo's POMs carry almost no `` tags. + +- **`application/`** — the deployable Spring Boot app (`codbex-hyperion-application`). Its `pom.xml` is the heart of the product: a long, deliberately-curated list of `org.eclipse.dirigible:dirigible-components-*` dependencies that selects exactly which engines, IDE views/editors/menus/perspectives, security providers, and templates ship in Hyperion. **To add or remove a platform feature, edit the dependency list here** rather than writing code. Note the `` that drop stock Dirigible pieces (e.g. `dirigible-components-ui-view-welcome`, `dirigible-components-ui-menu-help`) so the Hyperion overrides below take their place. +- **`components/`** — local Dirigible component overrides (`ui/view-welcome`, `ui/menu-help`) that replace the excluded stock ones. +- **`branding/`** — Hyperion logo, favicon, and branding `project.json` that override Dirigible defaults. +- **`integration-tests/`** — Selenium UI integration tests; no production code. + +The only hand-written Java in `application/` is the thin bootstrap: `HyperionApplication.java` (a `@SpringBootApplication` that `scanBasePackages = "org.eclipse.dirigible"` and excludes the JDBC/JPA auto-configs because Dirigible manages datasources itself) plus `AppLifecycleLoggingListener`. + +## Dirigible component model (how overrides work) + +A Dirigible component is a normal Maven jar whose real payload is **resources under `src/main/resources/META-INF/dirigible//`**, not Java classes. Inside that folder: +- `project.json` declares the component `guid`. +- `*.extension` files register an artifact at a Dirigible **extension point** (e.g. `view-welcome/extensions/welcome.extension` binds a config module to the `platform-views` extension point). +- `.html` / `.js` and `configs/` provide the UI and its configuration. + +The platform discovers everything on the classpath at runtime by scanning these extension points. So replacing a stock view = exclude the stock artifact in `application/pom.xml` + depend on a local component (in `components/`) that re-registers the same extension point with the same view id. Use `components/ui/view-welcome` as the reference example when creating a new override. + +## Integration tests + +Tests live in `integration-tests/src/test/java`, named `*IT`, and extend `HyperionIntegrationTest` (a thin subclass of Dirigible's `UserInterfaceIntegrationTest`). They drive a real browser via the `org.eclipse.dirigible.tests.framework` helpers (`IDE`, `browser.assertElementExistsByTypeAndText`, ...). They start the full application, so they only run under the `integration-tests` / `tests` profiles. + +## Spring profiles + +Default active profiles are `common,app-default` (see `application.properties`). **Eclipse Dirigible only fully activates when the `common` and `app-default` profiles are present** — when overriding `SPRING_PROFILES_ACTIVE`, keep them, e.g. `SPRING_PROFILES_ACTIVE=common,snowflake,app-default`. Security backends (`basic`, `keycloak`, `cognito`, `snowflake`) are selected by which `dirigible-components-security-*` dependency is active plus the chosen profile. From bfe41c5e4bde5e5861d98b3d83ff0806778afee7 Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:22:25 +0300 Subject: [PATCH 2/3] Place Hyperion in the codbex product family in CLAUDE.md Add context from codbex.com/products: each product is an edition selecting a subset of the shared platform; Hyperion's niche is BPM/BPMN. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index d403d1d..5171b63 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What this is -Hyperion is a codbex Edition product for **BPMN business-process modeling, management and operation**, built on the [Eclipse Dirigible](https://www.dirigible.io) low-code platform (Flowable as the BPM engine) packaged as a Spring Boot application. The repo itself contains very little business logic — it is primarily an **assembly**: it wires together a curated set of Dirigible component artifacts via Maven dependencies, adds branding, and overrides a few UI pieces. Understanding the architecture means understanding *what is assembled and how it is overridden*, not a large local codebase. +Hyperion is a codbex Edition product for **BPMN business-process modeling, management and operation** — Business Process Management fully compliant with BPMN v2, with **Flowable** as the BPM engine. It is built on the [Eclipse Dirigible](https://www.dirigible.io) low-code platform and packaged as a Spring Boot application. The repo itself contains very little business logic — it is primarily an **assembly**: it wires together a curated set of Dirigible component artifacts via Maven dependencies, adds branding, and overrides a few UI pieces. Understanding the architecture means understanding *what is assembled and how it is overridden*, not a large local codebase. + +Hyperion is one of several [codbex products](https://www.codbex.com/products/) — each is a Spring Boot **edition** that selects a different subset of the same shared platform's components (e.g. Atlas = the all-in-one edition, Helios = APIs, Hades = databases, Iapetus = integration/Camel, Phoebe = Airflow workflows). Hyperion's niche in that family is **BPM/BPMN**, which is why its dependency set centers on the BPM/Flowable engines, the Processes/Operations IDE perspectives, and BPM editors/menus/templates. Sibling repos follow the same assembly + override structure described below. Requires **JDK 21**. Default login is `admin` / `admin`; the app serves on port **80**. From f113b3d978910dab849e44e5195860bfcc910159 Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:24:06 +0300 Subject: [PATCH 3/3] Keep CLAUDE.md product context focused on Hyperion only Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5171b63..55aeafa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Hyperion is a codbex Edition product for **BPMN business-process modeling, management and operation** — Business Process Management fully compliant with BPMN v2, with **Flowable** as the BPM engine. It is built on the [Eclipse Dirigible](https://www.dirigible.io) low-code platform and packaged as a Spring Boot application. The repo itself contains very little business logic — it is primarily an **assembly**: it wires together a curated set of Dirigible component artifacts via Maven dependencies, adds branding, and overrides a few UI pieces. Understanding the architecture means understanding *what is assembled and how it is overridden*, not a large local codebase. -Hyperion is one of several [codbex products](https://www.codbex.com/products/) — each is a Spring Boot **edition** that selects a different subset of the same shared platform's components (e.g. Atlas = the all-in-one edition, Helios = APIs, Hades = databases, Iapetus = integration/Camel, Phoebe = Airflow workflows). Hyperion's niche in that family is **BPM/BPMN**, which is why its dependency set centers on the BPM/Flowable engines, the Processes/Operations IDE perspectives, and BPM editors/menus/templates. Sibling repos follow the same assembly + override structure described below. +Hyperion is a codbex **edition** — a Spring Boot product that selects a focused subset of the shared platform's components. Its niche is **BPM/BPMN**, which is why its dependency set centers on the BPM/Flowable engines, the Processes/Operations IDE perspectives, and BPM editors/menus/templates. (See for the product entry.) Requires **JDK 21**. Default login is `admin` / `admin`; the app serves on port **80**.