# kieler/elkjs architecture

> Architecture diagram of the GitHub repository kieler/elkjs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kieler/elkjs
- Repository: https://github.com/kieler/elkjs

## Overview

1. This repository is the JavaScript distribution layer for Eclipse ELK, a graph layout engine. Its boundary is clear: it accepts an ELK JSON graph, runs layout algorithms, and returns the same graph enriched with coordinates, routing, logging, and timing. It does not render diagrams or provide editor UI.

2. The architecture has two main runtime artifacts: an API layer and a worker/engine layer. The API layer is the small JavaScript-facing entrypoint (`src/js/elk-api.js`, `src/js/main-api.js`, `src/js/main-node.js`) that constructs `ELK`, normalizes options, and orchestrates calls. The engine layer is generated from Java/GWT sources and contains the actual layout algorithms.

3. The layout engine is rooted in `src/java` and `src/java-additional`. The `org.eclipse.elk.js` package contains the GWT module definitions and Node-specific linker support (`Elk.gwt.xml`, `ElkJs.gwt.xml`, `NodeJsModuleLinker.java`). The additional Java sources include adapters/utilities such as `JsonAdapter.xtend` and `SVGImage.java`, which bridge ELK’s Java object model to the JSON representation used by JavaScript.

4. Data flows from the caller into the API as an ELK JSON graph. The API passes graph data and layout options to the worker or direct engine. The engine mutates/returns the graph with layout results, and optionally emits `logging` and `executionTime` metadata when requested. That output is the only product of the system.

5. There are two execution modes. In browser environments, the library can run entirely in-page via the bundled build or via a separate `elk-worker.js` loaded with `Worker`. In Node.js, it can run directly without a worker or use a worker-thread compatible implementation when provided. This split is important to the architecture because the same public API can target different runtimes.

6. The build is a hybrid Java/JavaScript pipeline. Gradle and GWT compile the ELK Java sources into worker-side JavaScript, while npm/browserify-style packaging assembles the consumable JS files. The repository expects a sibling checkout of the ELK Java repository, which is the source of the actual layout algorithms.

7. The published package exposes multiple distribution shapes. `elk-api.js` is the API-only entrypoint, `elk-worker.js` is the compiled engine, `elk.bundled.js` is a browser-ready combined artifact, and the Node module entry points in `src/js/main-node.js` and `src/js/main-api.js` provide `require('elkjs')` convenience. This packaging boundary is central to the repo.

8. Typings in `typings/` provide the public TypeScript contract for the same API surface. They mirror the runtime entry points (`elk-api`, `elk-worker`, bundled variants) and are part of the consumer-facing boundary even though they do not affect execution.

9. The `test/` tree serves two roles: example integrations and automated verification. The example files show browser, Node, and webworker usage patterns, while the Mocha tests validate API behavior, known algorithms/options, logging, IDs, error handling, and regression cases. This suggests the repo’s critical risks are compatibility and packaging rather than core algorithm correctness, which lives upstream in ELK.

10. Operationally, the project is published as an npm package and also has CI/CD via GitHub Actions. The release process builds the generated artifacts into `lib/`, publishes to npm, and relies on the ELK version alignment described in the README. For architecture diagrams, the important external dependency is the upstream Eclipse ELK codebase; this repository is primarily the JavaScript bridge, packaging, and runtime wrapper around it.

Main entry points: [`src/java/org/eclipse/elk/js/ElkJs.java`](https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/ElkJs.java) (ELK JS), [`build.gradle`](https://github.com/kieler/elkjs/blob/master/build.gradle) (Gradle build), [`src/js/elk-api.js`](https://github.com/kieler/elkjs/blob/master/src/js/elk-api.js) (elk-api), [`package.json`](https://github.com/kieler/elkjs/blob/master/package.json) (npm package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_src_js_elk_api["elk-api<br/>js entrypoint<br/>[elk-api.js]"]
  node_src_js_main_api["main api<br/>node entrypoint<br/>[main-api.js]"]
  node_src_js_main_node["main node<br/>node entrypoint<br/>[main-node.js]"]
  node_dist_api["API bundle<br/>published artifact"]
  node_dist_worker["Worker bundle<br/>published artifact"]
  node_dist_bundled["Bundled build<br/>published artifact"]
end

subgraph group_engine["Layout Engine"]
  node_src_java_elkjs["ELK JS<br/>gwt module<br/>[ElkJs.java]"]
  node_src_java_elk_gwt["ELK GWT<br/>gwt module<br/>[Elk.gwt.xml]"]
  node_src_java_elkjs_gwt["ELK JS GWT<br/>gwt module<br/>[ElkJs.gwt.xml]"]
  node_src_java_node_linker["Node linker<br/>gwt linker"]
  node_src_java_additional_json["JSON adapter<br/>xtend adapter<br/>[JsonAdapter.xtend]"]
  node_src_java_additional_svg["SVG image<br/>java utility<br/>[SVGImage.java]"]
  node_upstream_elk[("ELK core<br/>upstream layout engine")]
end

subgraph group_build["Build & Release"]
  node_build_gradle["Gradle build<br/>build script<br/>[build.gradle]"]
  node_pkg_npm["npm package<br/>package manifest<br/>[package.json]"]
  node_github_actions["CI/CD<br/>workflow<br/>[ci.yml]"]
end

subgraph group_quality["Validation"]
  node_typings_api["Typings<br/>typescript defs<br/>[elk-api.d.ts]"]
  node_tests_examples["Examples<br/>usage samples"]
  node_tests_mocha["Mocha tests<br/>test suite"]
end

node_src_js_elk_api -->|"invoke layout"| node_src_java_elkjs
node_src_js_elk_api -->|"exported by"| node_src_js_main_api
node_src_js_main_api -->|"node entry"| node_src_js_main_node
node_src_js_main_api -->|"packages"| node_dist_api
node_src_js_main_node -->|"consumes"| node_dist_api
node_src_java_elkjs -->|"configured by"| node_src_java_elkjs_gwt
node_src_java_elkjs -->|"inherits from"| node_src_java_elk_gwt
node_src_java_elkjs -->|"links for node"| node_src_java_node_linker
node_src_java_elkjs -->|"adapts graphs"| node_src_java_additional_json
node_src_java_elkjs -->|"uses"| node_src_java_additional_svg
node_src_java_elkjs -->|"delegates to"| node_upstream_elk
node_src_java_additional_json -->|"bridges model"| node_upstream_elk
node_build_gradle -->|"compiles"| node_src_java_elkjs
node_build_gradle -->|"emits"| node_dist_worker
node_build_gradle -->|"assembles"| node_dist_bundled
node_pkg_npm -->|"publishes"| node_dist_api
node_pkg_npm -->|"publishes"| node_dist_worker
node_pkg_npm -->|"publishes"| node_dist_bundled
node_github_actions -->|"runs"| node_build_gradle
node_typings_api -->|"describes"| node_dist_api
node_tests_examples -->|"demonstrate"| node_src_js_elk_api
node_tests_mocha -->|"verify"| node_src_js_elk_api
node_tests_mocha -->|"verify"| node_dist_worker

click node_src_js_elk_api "https://github.com/kieler/elkjs/blob/master/src/js/elk-api.js"
click node_src_js_main_api "https://github.com/kieler/elkjs/blob/master/src/js/main-api.js"
click node_src_js_main_node "https://github.com/kieler/elkjs/blob/master/src/js/main-node.js"
click node_src_java_elkjs "https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/ElkJs.java"
click node_src_java_elk_gwt "https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/Elk.gwt.xml"
click node_src_java_elkjs_gwt "https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/ElkJs.gwt.xml"
click node_src_java_node_linker "https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/linker/NodeJsModuleLinker.java"
click node_src_java_additional_json "https://github.com/kieler/elkjs/blob/master/src/java-additional/org/eclipse/elk/graph/json/JsonAdapter.xtend"
click node_src_java_additional_svg "https://github.com/kieler/elkjs/blob/master/src/java-additional/org/eclipse/elk/alg/common/utils/SVGImage.java"
click node_build_gradle "https://github.com/kieler/elkjs/blob/master/build.gradle"
click node_pkg_npm "https://github.com/kieler/elkjs/blob/master/package.json"
click node_github_actions "https://github.com/kieler/elkjs/blob/master/.github/workflows/ci.yml"
click node_typings_api "https://github.com/kieler/elkjs/blob/master/typings/elk-api.d.ts"
click node_tests_examples "https://github.com/kieler/elkjs/tree/master/test/examples"
click node_tests_mocha "https://github.com/kieler/elkjs/tree/master/test/mocha"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_js_elk_api,node_src_js_main_api,node_src_js_main_node,node_dist_api,node_dist_worker,node_dist_bundled toneBlue
class node_src_java_elkjs,node_src_java_elk_gwt,node_src_java_elkjs_gwt,node_src_java_node_linker,node_src_java_additional_json,node_src_java_additional_svg,node_upstream_elk toneAmber
class node_build_gradle,node_pkg_npm,node_github_actions toneMint
class node_typings_api,node_tests_examples,node_tests_mocha toneRose
```

## Components

### Public API

Consumer entrypoints and distribution shapes.

- [elk-api](https://github.com/kieler/elkjs/blob/master/src/js/elk-api.js): js entrypoint · Main JavaScript API constructor and orchestration entrypoint. · `src/js/elk-api.js`
- [main api](https://github.com/kieler/elkjs/blob/master/src/js/main-api.js): node entrypoint · Node/browser-facing API wrapper for the package entrypoint. · `src/js/main-api.js`
- [main node](https://github.com/kieler/elkjs/blob/master/src/js/main-node.js): node entrypoint · Node.js module entrypoint for direct consumption. · `src/js/main-node.js`
- **API bundle**: published artifact · API-only distribution exposed to consumers.
- **Worker bundle**: published artifact · Compiled engine bundle loaded directly or in a worker.
- **Bundled build**: published artifact · Browser-ready combined artifact.

### Layout Engine

Generated GWT/Java sources that run layout.

- [ELK JS](https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/ElkJs.java): gwt module · GWT module and Java bridge entrypoint. · `src/java/org/eclipse/elk/js/ElkJs.java`
- [ELK GWT](https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/Elk.gwt.xml): gwt module · Top-level GWT module definition for the ELK Java sources. · `src/java/org/eclipse/elk/Elk.gwt.xml`
- [ELK JS GWT](https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/ElkJs.gwt.xml): gwt module · JavaScript-targeted GWT module definition. · `src/java/org/eclipse/elk/js/ElkJs.gwt.xml`
- [Node linker](https://github.com/kieler/elkjs/blob/master/src/java/org/eclipse/elk/js/linker/NodeJsModuleLinker.java): gwt linker · Node.js module linker for GWT output. · `src/java/org/eclipse/elk/js/linker/NodeJsModuleLinker.java`
- [JSON adapter](https://github.com/kieler/elkjs/blob/master/src/java-additional/org/eclipse/elk/graph/json/JsonAdapter.xtend): xtend adapter · Bridges ELK graph objects to the JSON representation. · `src/java-additional/org/eclipse/elk/graph/json/JsonAdapter.xtend`
- [SVG image](https://github.com/kieler/elkjs/blob/master/src/java-additional/org/eclipse/elk/alg/common/utils/SVGImage.java): java utility · Utility support for image handling in the layout model. · `src/java-additional/org/eclipse/elk/alg/common/utils/SVGImage.java`
- **ELK core**: upstream layout engine · External Java repository providing the actual layout algorithms.

### Build & Release

Compilation, packaging, and publishing pipeline.

- [Gradle build](https://github.com/kieler/elkjs/blob/master/build.gradle): build script · Java/GWT build orchestration and artifact generation. · `build.gradle`
- [npm package](https://github.com/kieler/elkjs/blob/master/package.json): package manifest · Package metadata and consumer distribution configuration. · `package.json`
- [CI/CD](https://github.com/kieler/elkjs/blob/master/.github/workflows/ci.yml): workflow · Continuous integration and release workflows. · `.github/workflows/ci.yml`

### Validation

Examples, tests, and public typings.

- [Typings](https://github.com/kieler/elkjs/blob/master/typings/elk-api.d.ts): typescript defs · Public TypeScript contracts for the runtime entrypoints. · `typings/elk-api.d.ts`
- [Examples](https://github.com/kieler/elkjs/tree/master/test/examples): usage samples · Integration examples for browser, Node, and worker runtimes. · `test/examples`
- [Mocha tests](https://github.com/kieler/elkjs/tree/master/test/mocha): test suite · Behavioral and regression tests for API, options, logging, and errors. · `test/mocha`

## Connections

- elk-api → ELK JS: invoke layout · API forwards graph and options into the engine.
- elk-api → main api: exported by · Main API wrapper exposes the constructor to consumers.
- main api → main node: node entry · Node entrypoint reuses the same public API surface.
- main api → API bundle: packages · API entrypoint becomes the published API artifact.
- main node → API bundle: consumes · Node module entrypoint resolves the packaged API surface.
- ELK JS → ELK JS GWT: configured by · GWT module definition drives JS-targeted compilation.
- ELK JS → ELK GWT: inherits from · Java/GWT build is rooted in the broader ELK module.
- ELK JS → Node linker: links for node · Node-specific linker shapes CommonJS output.
- ELK JS → JSON adapter: adapts graphs · JSON adapter maps ELK objects to the JS graph model.
- ELK JS → SVG image: uses · Additional utilities support engine-side data handling.
- ELK JS → ELK core: delegates to · Generated bridge depends on upstream algorithm implementations.
- JSON adapter → ELK core: bridges model · Adapter translates between the ELK Java model and JSON.
- Gradle build → ELK JS: compiles · Gradle/GWT build produces the JavaScript engine bundle.
- Gradle build → Worker bundle: emits · Build produces the worker-side compiled artifact.
- Gradle build → Bundled build: assembles · Build assembles the browser-ready combined distribution.
- npm package → API bundle: publishes · npm package exposes the API-only distribution.
- npm package → Worker bundle: publishes · npm package exposes the worker bundle.
- npm package → Bundled build: publishes · npm package exposes the browser bundled build.
- CI/CD → Gradle build: runs · CI and release workflows execute the build pipeline.
- Typings → API bundle: describes · Type definitions mirror the API entrypoint.
- Examples → elk-api: demonstrate · Examples exercise browser, Node, and worker usage.
- Mocha tests → elk-api: verify · Tests validate API behavior and distribution compatibility.
- Mocha tests → Worker bundle: verify · Tests cover worker-oriented runtime behavior.