Add design documentation for extension mechanism by wborn · Pull Request #9 · openremote/extensions

wborn · 2026-02-19T14:31:42Z

Introduces the Technical Design Specification for decoupling domain-specific logic (Energy, Protocols, UI) from the platform Core.

Closes openremote/openremote#2327

Introduces the Technical Design Specification for decoupling domain-specific logic (Energy, Protocols, UI) from the platform Core. Closes openremote/openremote#2327

ebariaux

That's a great start, I think you covered quite a bit of ground and it's good to have things explicitly described and written down.

I made quite a few comments that I think will be subjective. My proposal would be that once there's been feedback from a few reviewers, we organise a session to go over all the remarks and align on a direction to proceed with.

pierrekil · 2026-03-04T15:02:56Z

For agents, also ENTSOE, openWeather, battery simulator might become extensions

pierrekil · 2026-03-04T15:07:17Z

@remyberden and @pierrekil: Good to think about naming conventions and way we explain from a marketing communication perspective to less/non technical users.

MartinaeyNL

This is a really well written document! Thanks! 👏

Only two small comments from my own pair of eyes. (and field of expertise I guess)
Feel free to respond or explain details.

MartinaeyNL · 2026-03-05T10:52:43Z

+energy/
+├── src/main/java/org/openremote/extension/energy/
+│   ├── model/                         # Java Asset implementations
+│   │   ├── ElectricityAsset.java
+│   │   └── EnergyModelProvider.java   # Implements AssetModelProvider SPI
+│   ├── manager/                       # Core logic & Container services
+│   │   └── EnergyOptimisationService.java # Implements ContainerService SPI
+├── src/main/resources/
+│   ├── org/openremote/extension/energy/setup/database/ # Flyway scripts
+│   │   └── V20260131_01__RenameEnumValues.sql
+│   └── META-INF/services/             # SPI Registration
+│       ├── org.openremote.model.AssetModelProvider
+│       ├── org.openremote.model.ContainerService
+│       ├── org.openremote.model.ExtensionMetadata
+│       └── org.openremote.model.setup.SetupTasks
+├── src/test/groovy/org/openremote/extension/energy/
+│   ├── EnergyOptimisationTest.groovy  # Spock Integration Tests
+│   ├── ForecastSolarServiceTest.groovy
+│   └── ManagerTestSetup.groovy        # Test-specific environment logic
+└── src/test/resources/
+    └── META-INF/services/
+        └── org.openremote.model.setup.SetupTasks # Test-only setup tasks


Out of curiosity, don't extensions have their own build.gradle file?
As in, I assume extensions can have their own third party dependencies outside of OpenRemote.
And the list of "other extensions it depends on" would be in one central place,
so either in build.gradle or inside the org.openremote.model.ExtensionMetadata file, not both.
Or do I misunderstand something?

Gradle dependencies and extension dependencies serve different purposes.

Gradle defines the dependencies required to build and run the extension code, while ExtensionMetadata defines logical dependencies used by Manager for extension activation and validation. These may overlap, but don't necessarily have to. For example, a composite extension could depend on several other extensions without having compile-time dependencies on them.

For the initial implementation the extension dependencies are explicitly declared in ExtensionMetadata to keep things simple. We could later consider deriving or validating this information from the Gradle configuration if that proves useful.

Also added build.gradle to the extension artifact layout diagram for completeness.

MartinaeyNL · 2026-03-05T10:55:05Z

+The `OR_ENABLED_EXTENSIONS` environment variable is introduced.
+
+* **Behavior**: The Manager filters the discovered `ExtensionMetadata` list. The Manager automatically activates all transitive dependencies declared in the metadata.
+* **Persistence**: The list of active extension IDs is persisted in `manager_config.json`.


I'm totally against persisting this info inside the manager_config.json 😂
It's better to, as a first step, introduce a simple HTTP GET endpoint to retrieve the list of installed extensions.
That would prevent multiple sources of truth, and prevents breaking changes when extending this API.

Just got context from @wborn on what the persistence is meant for.

Apparently it's the other way around, where we would persist OR_ENABLED_EXTENSIONS inside the manager_config.json file. However, this is not the intended use of this config file, as it's the "configuration of the Manager User Interface". So we'd probably store this in a separate extensions.json file instead.

Yes it's probably better to persist it in another file. I've removed this implementation detail in 599c232.

…ism-design

Ekhorn · 2026-09-11T17:17:17Z

+### Dependency Management (Build-time)
+
+Extensions are developed as independent Gradle projects.
+To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle`.


Suggested change

To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle`.

To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle` file.

Ekhorn · 2026-09-11T17:17:32Z

+To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle`.
+
+- **Transitive Dependencies**: Gradle handles the resolution of shared libraries between the Core and multiple extensions, ensuring a consistent and conflict-free classpath.
+- **Composition**: Composite Extensions define a collection of dependencies in their `build.gradle`, allowing a developer to include a single "Composite" artifact to pull in a complete suite of functional and data modules.


Suggested change

- **Composition**: Composite Extensions define a collection of dependencies in their `build.gradle`, allowing a developer to include a single "Composite" artifact to pull in a complete suite of functional and data modules.

- **Composition**: Composite Extensions define a collection of dependencies in their `build.gradle` file, allowing a developer to include a single "Composite" artifact to pull in a complete suite of functional and data modules.

Ekhorn · 2026-09-11T17:18:09Z

+### Repository Structure
+
+The monorepo uses Gradle subprojects to isolate each extension.
+A shared `build.gradle` in the root provides common build logic, ensuring all extensions use the same compiler settings and dependency versions.


Suggested change

A shared `build.gradle` in the root provides common build logic, ensuring all extensions use the same compiler settings and dependency versions.

A shared `build.gradle` file in the root provides common build logic, ensuring all extensions use the same compiler settings and dependency versions.

Ekhorn · 2026-09-11T17:42:39Z

+- **Discovery**: The Manager discovers the available extensions through the `ExtensionMetadata` SPI.
+- **Activation**: The Manager determines the active extension set from `OR_ENABLED_EXTENSIONS` and automatically includes transitive extension dependencies declared in the metadata.
+- **Component Filtering**: `AssetModelProvider`, `SetupTasks`, `ContainerService`, and other extension components belonging to inactive extensions are not initialized or registered. The existing SPI discovery mechanisms therefore need to become extension-aware.
+- **Validation**: The Manager validates that required extension dependencies are present and detects invalid or circular dependency configurations before initialization.


I assume "invalid" includes conflicting asset types, or other model definition names? And so thinking about the future. If we ever have e.g. "unofficial" extensions conflicting with "official" asset types people using "UI-Driven Configuration" would need be informed about this.

Add design documentation for extension mechanism

454e50b

Introduces the Technical Design Specification for decoupling domain-specific logic (Energy, Protocols, UI) from the platform Core. Closes openremote/openremote#2327

wborn added the Documentation Improvements or additions to documentation label Feb 19, 2026

ebariaux reviewed Feb 23, 2026

View reviewed changes

Comment thread DESIGN.md

ebariaux reviewed Feb 23, 2026

View reviewed changes

MartinaeyNL reviewed Mar 5, 2026

View reviewed changes

Ekhorn reviewed Mar 9, 2026

View reviewed changes

Comment thread DESIGN.md

Ekhorn reviewed Mar 9, 2026

View reviewed changes

Comment thread DESIGN.md Outdated

MartinaeyNL and others added 3 commits March 10, 2026 13:49

Merge branch 'main' into docs/extension-mechanism-design

1f41187

Merge remote-tracking branch 'origin/main' into docs/extension-mechan…

777f7cf

…ism-design

Apply Spotless formatting

4528903

wborn mentioned this pull request Sep 1, 2026

Consider migrating package namespace from org.openremote to io.openremote openremote/openremote#3257

Open

3 tasks

wborn added 11 commits September 1, 2026 15:22

Clarify extension behavior

1e78961

Clarify extension external dependencies

97be7ca

Merge remote-tracking branch 'origin/main' into docs/extension-mechan…

2c06634

…ism-design

Update diagram

b6945c5

Clarify when ExtensionMetadata is required in activation roadmap

599c232

Clarify UI configuration

6cd9e7a

Improve Versioning & Release Management

e3d2689

Correct bullets

293753c

Clarify Docker Contract

1858cd7

Rework extension types

1eaeceb

Rework Database Migrations

226b174

wborn requested review from a team, Ekhorn, MartinaeyNL and ebariaux September 2, 2026 14:14

Merge branch 'main' into docs/extension-mechanism-design

61a002c

Ekhorn reviewed Sep 11, 2026

View reviewed changes

	To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle`.
	To include an extension in an OpenRemote deployment, it is added as a standard dependency in the project's `build.gradle` file.

	- Composition: Composite Extensions define a collection of dependencies in their `build.gradle`, allowing a developer to include a single "Composite" artifact to pull in a complete suite of functional and data modules.
	- Composition: Composite Extensions define a collection of dependencies in their `build.gradle` file, allowing a developer to include a single "Composite" artifact to pull in a complete suite of functional and data modules.

	A shared `build.gradle` in the root provides common build logic, ensuring all extensions use the same compiler settings and dependency versions.
	A shared `build.gradle` file in the root provides common build logic, ensuring all extensions use the same compiler settings and dependency versions.

Uh oh!

Conversation

wborn commented Feb 19, 2026

Uh oh!

Uh oh!

ebariaux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pierrekil commented Mar 4, 2026

Uh oh!

pierrekil commented Mar 4, 2026

Uh oh!

MartinaeyNL left a comment

Choose a reason for hiding this comment

Uh oh!

MartinaeyNL Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

wborn Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

MartinaeyNL Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MartinaeyNL Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

wborn Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Ekhorn Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Ekhorn Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Ekhorn Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Ekhorn Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

MartinaeyNL Mar 5, 2026 •

edited

Loading

Ekhorn Sep 11, 2026 •

edited

Loading