ADR 0001: Module system for implementation-specific functionality
| Status | Accepted (2026-11-03); implemented in develop |
| Epic | OGC-1577; this record closes Phase 0 (OGC-1585) |
| Design | specs/plans/module-system-architecture.md (sections 7, 9, 10, 13, 24 and 25) |
| Deciders | OpenELIS core maintainers (DIGI) |
Context
Implementation-specific functionality is built into the core repository today:
Java in the WAR, React pages in the single bundle, Liquibase changesets in the
core changelog, menu rows and permission keys in core seeds. The design document
records the evidence (35 implementation-named commits on develop, an
1,839-line App.jsx, 174 hand-listed entity classes, dozens of feature toggles)
and the consequences: core grows with every implementation, one implementation's
feature can regress another, and implementation teams cannot develop, test,
version or deploy their own functionality independently.
The design document compares five backend models and four frontend models (section 7) and reconciles them with the companion comparison OpenELIS Modularization Plan: Comparing Architecture Models (Ian Bacher, internal review, 2026-10-28). This record states the decision and settles the open questions the design left to Phase 0 (section 25.2) so that Phase 1 can start.
Decision
OpenELIS Global gets a manifest-driven module system: one artifact type, a
module JAR described by META-INF/openelis-module.json, in two shapes
(provider: extension-point implementations only; module: beans, REST
controllers under /rest/modules/<id>/, JPA entities, a Liquibase changelog,
permissions, menu entries and a prebuilt frontend remote). Modules are
discovered at application start from /var/lib/openelis-global/modules, each
loaded by its own parent-first class loader and wired into its own child
Spring context whose parent is the core root context. The React application
becomes an application shell that reads /rest/module-registry, registers
module routes behind the existing SecureRoute gate and lazy-loads module
bundles from the same origin. Inside the core, ArchUnit rules with a frozen
baseline (CoreBoundariesArchitectureTest) describe the feature boundaries; the
test is skipped (@Ignore) until the team decides to enforce it (OGC-1582),
since existing code already breaks the rules.
Models considered and set aside (design section 7): convention-only classpath scanning (no identity, no compatibility, no migrations), module-first class loading (two copies of a framework in one JVM), module beans in the root context (a module could replace or advise core beans), out-of-process modules (no shared session or transaction; kept for integrations such as the Analyzer Bridge), general-purpose plugin frameworks (PF4J, OSGi, JPMS layers: thin Spring integration, repackaging of the core, nothing for the frontend), a library-assembled core (sites without Java developers would have to build their own server) and, on the frontend, build-time integration, single-spa and plain import maps (kept as the fallback loader).
Decisions on the open questions (design section 25.2)
| # | Question | Decision | Reasoning |
|---|---|---|---|
| 1 | Publishing of openelis-spi, openelis-module-api, openelis-core classes, the BOM and @openelis/module-sdk |
Built by the core build and installed to the local Maven repository (mvn install) and the frontend workspace; a module repository's CI checks out the core at the tag named in its requires.openelis and installs it before building. Publication to a remote repository (GitHub Packages for Maven and npm) is a Phase 5 operations item. |
No remote repository exists for the project's artifacts today (the dataexport submodule follows the same local-install pattern); a module can be built and tested without waiting for a publishing pipeline. |
| 2 | Package naming | Every module class lives under org.openelisglobal.module.<name>: backend.basePackages, the activator, the entities and the extension classes. The sub-packages the core owns (api, manifest, runtime, web, testkit) are reserved and the validator refuses any other package. |
One namespace for everything that is a module keeps module classes recognizable in logs, stack traces and the coupling report, and a child context can only ever scan org.openelisglobal.module.<name>, never a core package; module JARs stay off the webapp class path, so the core scan never sees them. |
| 3 | Strict mode default | Opt-in. A modules.lock digest allowlist is honoured when present and refused JARs are INVALID; a deployment without the file runs every JAR in the directory. |
Installation already requires filesystem access to the deployment checkout, which is the trust boundary; strict mode is an additional control sites can switch on. |
| 4 | Core access policy for providers | Report, do not refuse. The registry's core-coupling report lists which of the three core artifacts a module references; the template keeps openelis-core out of a provider's dependencies. |
A refusal would turn a packaging mistake into a start-up failure for a working provider. |
| 5 | Schema layout | Module tables and sequences live in the clinlims schema with the mandatory prefix mod_<id>_ (hyphens replaced by underscores). |
One schema keeps backups, the existing JNDI datasource and the Liquibase databasechangelog table unchanged; the prefix makes module objects recognisable and removable. |
| 6 | Uninstall data policy | Retain tables and permission rows when a module is removed. | Follow-up and audit data must survive an operator removing a JAR; a module may ship an uninstall changelog for an administrator to run explicitly. |
| 7 | Route policy | Module routes live under /m/<id>/ only (admin pages under /admin/m/<id>/). Top-level paths are not accepted in this version. |
Core routes are still JSX in App.jsx, not data, so a top-level module path cannot be checked for collisions; the prefix makes a collision impossible. Allowing top-level paths once core routes are data is an additive change. |
| 8 | Phase 6 candidate | The Specimen Follow-up & Action Tracker module, developed in its own repository (mozzy11/openelis-module-specimen-followup), is the first module-native workflow and the proof of the architecture: it owns its tables, reuses PatientService, the sample services and the user directory, contributes a Samples menu entry and its pages, and ships a complete create, list, detail, update and delete workflow. OGC-1144 remains a later candidate. |
A workflow that references existing patients and specimens without touching core tables exercises every contract the design names (discovery, migrations, permissions, menu, routes, core-service reuse, authorisation) on a real screen flow. |
| 9 | Governance | New extension points, facades and extension slots are added by core pull request, reviewed by the core maintainers; the exposed core UI index and the slot catalogue are listed in the SDK changelog. | Same review path as every other core change. |
| 10 | Fail policy | Fail-fast after validation: an INVALID, INCOMPATIBLE or DISABLED module is skipped and reported and the core starts; a module that fails migration, context refresh or onStart stops start-up naming the module. modules.failurePolicy=isolate is not implemented in this version. |
A laboratory system must not run with an unknown subset of its features; the one-file disable marker and modules.<id>.enabled=false give the operator a recovery that needs no code. |
| 11 | Extension-point ownership | The core maintainers own openelis-spi; it is versioned on its own cadence and only changes by core pull request; a breaking change is an SPI major. |
The SPI is the narrowest contract and the one providers depend on most. |
| 12 | First report to move behind the report extension point | Deferred. The report extension point and the ReportImplementationFactory seam are implemented; moving an existing site-specific report into a provider is scheduled with the implementation team that still uses it. |
No implementation team was available during this phase to confirm byte-for-byte output of a moved report. |
| 13 | Decision record sign-off | The core maintainers sign this record through the pull request that merges it; the community may review it on the forum when the module system is proposed for develop. |
Keeps the record in the same review flow as the code. |
| 14 | Loader engine | The design's own parent-first URLClassLoader subclass. PF4J is not adopted. |
A few hundred lines of JDK code with no second framework to keep in step with Spring; PF4J's default is plugin-first and its Spring bridge is thin. |
| 15 | Who serves module files | The webapp serves a module's frontend files from the JAR, as decision checks D2 and D4 assume: remoteEntry.js, the chunks and the message bundles are published under /modules/<id>/<sha16>/ (the running JAR's digest), compressed by Tomcat's connector and immutable for a year, with a weak ETag answered before the JAR is read (OGC-1637, OGC-1638). Serving them from the frontend container's nginx and assembling the frontend at build time both stay rejected (OGC-1643, 2026-11-17). |
The 2026-11-09 module frontend review measured the pilot's serving costs (files uncompressed, revalidated on every load, read whole from the JAR) and separated three choices inside "bundling": the module builds its frontend, modules join the shell at start-up, and Tomcat serves the files. Only the third caused the costs, and the two tickets removed them with no deployment change: the JAR stays the only artifact, a .jar.disabled marker or a removed JAR takes pages and endpoints away together, the offline package carries nothing extra, and no extraction step or helper process exists per install, upgrade or disable. nginx serving would need an extraction step on every module change that knows about disabled JARs, a modules directory visible to the frontend container, a copy of the digest logic in the proxy and offline-package changes, to gain what the two tickets deliver; a frontend-only fix restarts the webapp either way because the frontend is inside the JAR, and the review found no evidence that frontend-only fixes are frequent. Build-time assembly is a separate proposal against D2 and D4; nothing in the pilot's numbers calls for it. |
Decision checks (design section 24, Phase 0)
| # | Check | Result | Effect on the decision |
|---|---|---|---|
| D1 | How sites differ today | The repository inventory (design section 2.4): reports, billing, notification channels, accession formats and the client registry are swaps at one point; the vector surveillance domain and the planned additional-information workflow are whole features; analyzers already sit behind the Bridge. Implementation forks and local patches were not surveyed in this phase. | Confirms providers for the swaps and full modules for whole workflows. |
| D2 | Who builds extensions | Both: implementation teams with Java developers (the forks named in D1) and sites that can only drop a JAR into configs/modules. |
Confirms the two shapes and the restart-to-install model. |
| D3 | Upgrade breakage history | Not tagged in this phase (needs the release history reviewed with the implementation teams). | Open; does not block Phase 1. |
| D4 | Demand for other assemblies | No request on record for a referral-only or consolidated assembly. | A library-assembled core stays out of scope. |
| D5 | Feature coupling | Measured by CoreBoundariesArchitectureTest (Phase 1): 232 cross-feature DAO dependencies and 71 controller-to-DAO dependencies, frozen in src/test/resources/archunit_store; the feature packages form one cycle cluster (ArchUnit stops counting at 100 cycles), so the cycle rule is reported, not frozen, until the cluster is broken up. |
The baseline is the starting point for closing violations feature by feature. |
| D6 | Entity and schema entanglement | Entities are mapped by hand-listed hbm.xml files and annotated classes across feature packages; the schema stays shared (decision 5). |
Confirms prefixed module tables in the shared schema. |
| D7 | Report SPI width | ReportProvider needs the report id, the request parameters, the requesting user and the locale in, and bytes with a content type out: four value types, no core entity. |
Confirms a narrow, versionable SPI. |
| D8 | Closing the reporting feature | Not started; scheduled after Phase 1 with the frozen baseline. | Open; does not block Phase 1. |
| D9 | Spring Boot outlook | Not planned. | ArchUnit, not Spring Modulith. |
| D10 | Install and CI cost | Module loading adds a mounted directory to the compose file and no Tomcat change; the ArchUnit test runs with the Backend workflow. Measured when each phase lands. | Confirms the operating model. |
Consequences
- A module can ship a complete workflow (schema, services, REST API, pages, navigation, permissions) without a core pull request, built and versioned in its own repository against three published core artifacts.
- The core never sees module beans; only declared extensions, controllers under the module path and forwarded events cross the boundary. A module cannot replace or advise a core bean.
- Modules are trusted code with the application's privileges. There is no sandbox; installation is a file operation in the deployment checkout followed by a restart.
- Every module declares the minimum OpenELIS version it was built against; a module the running version cannot satisfy is reported and skipped.
- With no modules installed, start-up and behaviour are unchanged; the module runtime is verified by its own tests and by the example module the core CI loads.
- Module tables, permission keys, message keys, menu ids, REST paths and routes all derive from the module id, which keeps every namespace rule mechanical.
- The core takes on new maintenance: the SPI and module API versioning, the exposed core UI index, the slot catalogue and the ArchUnit baseline.
Implementation
The work landed in one pull request per phase (OGC-1578 contracts, OGC-1579 backend runtime, OGC-1580 frontend shell, OGC-1581 example module and packaging, OGC-1582 operations), with the Specimen Follow-up & Action Tracker module (OGC-1583, DIGI-UW/openelis-module-specimen-followup) developed outside the core as the example module.