kieler/elkjs

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.