arc42, the Template for documentation of software and system architecture.
By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.
Template Revision: 7.0 EN (based on asciidoc), January 2017
© We acknowledge that this document uses material from the arc 42 architecture template, https://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.
1. Introduction and Goals
Good diagrams are very important for a good documentation. diagrams.net is open source, online, desktop and container deployable diagramming software which does an amazing job.
One of the main features is that it is able to store the sources of the diagram within the meta data of a
That makes it ideal for the Docs-as-Code approach for documenting software.
Those images can be directly embedded in AsciiDoc documents but still remain editable.
This way, you never lose the source of your diagrams.
HINT: diagrams.net was formerly known as draw.io and many plugins, tools and docs still use this name.
1.1. Task Definition
The goal is to create a plugin for IntelliJ based IDEs which
adds a recognizable icon to all diagrams.net files,
opens diagrams.net files in the diagrams.net editor, and
saves them in the same format as they were.
Additional tasks might be added in the future.
1.2. Quality Goals
It is expected that the diagrams.net files are under version control. So, corrupted files will be easily recovered. Nevertheless, the main quality goal is that the editor will be stable (no crashed will editing) and the load/save mechanism will not corrupt files.
Data protection is crucial. The second quality goal is that no data leaves the local system. If it is necessary to run diagrams.net on a server, it should be possible to set up your own server.
See also data security statement of draw.io
Not everybody is always online. The third quality goal is that the plugin should also work offline.
2. Architecture Constraints
This plugin is intended for the IntelliJ based IDEs. This bringst up some constraints.
the plugin has to be written in a JVM based language
the plugin has to run with the minimum system requirements of IntelliJ
2 GB of free RAM
2.5 GB disk space and another 1 GB for caches
Monitor Resolution 1024x768
64-bit Operating System
starting with IntelliJ 2020.2, the JavaFX based browser solution within IntelliJ will be deprecated and replaced with the Chromium Embedded Framework (CEF) in its Java based version (JCEF). So, the architecture has to support JCEF.
current IntelliJ ships with Java 11 as runtime. So the system must run on Java 11 and higher.
3. System Scope and Context
This plugin focuses only on IntelliJ and editing of diagrams.
Other IDEs or modification of diagrams are out of scope.
3.1. Business Context
let’s use the C4 PlantUML syntax here!
3.2. Technical Context
4. Solution Strategy
diagrams.net is a web based diagramming tool which runs in different browsers. Since IntelliJ version 2020.01, JetBrains added the JCEF - Java Chromium Embedded Framework to its platform.
This enables us to use the powerful chromium browser to run diagrams.net within IntelliJ.
The diagrams.net documentation has good examples on how to embedd diagrams.not in a stand aline, local HTML page. These where used as a starting point, together with the knowledge of Henning Dieterichs, the author of the draw.io plugin for VS Code. He learned a lot about draw.io while writing his plugin and thus helped to get draw.io up and running as offline solution.
The Kotlin based IntelliJ Plugin and the web based draw.io communicate via event messages. See Chapter 06 for more details.
Unresolved directive in index.adoc - include::chapters/05_building_block_view.adoc
5. Runtime View
The following sequence diagrams will help you to understand the inner workings of the plugin.
5.1. RTS 01: Init Plugin Editor
Figure 1 shows the simplified sequence on how the plugin editor is instantiated.
While the file extensions for the fileType-plugin are specified directly in the
plugin.xml file, there is a different mechanism for the fileEditor-Plugin.
file to the
This method could now inspect the file and check if it will provide an editor for it.
In our case, we just check the file extension.
accept() returns a
true, IntelliJ will create and Display the
5.2. RTS 02: Init WebView
6. RTS 03: Autosave
Unresolved directive in index.adoc - include::chapters/07_deployment_view.adoc
Unresolved directive in index.adoc - include::chapters/08_concepts.adoc
7. Design Decisions
7.1. ADR 01: Plugin Programming Language
IntelliJ is JVM based and plugins can be written in one of many languages which create bytecode for the JVM. One of those languages have to be selected.
This plugin uses Kotlin as programming language.
As Ralf Müller (rdmueller) is mostly experienced in Groovy, he started to implement the plugin in Groovy. Since most plugin examples he tried to learn from, are written in Java, he soon switched over to Java.
With the experience of Alexander Schwartz (ahus1) - the maintainer of the asciidoctor plugin for IntelliJ - we dropped Groovy and the first proof of concept has been implemented in Java.
When Henning Dieterichs (hediet)- the maintainer of the VS Code draw.io plugin - joined the project, he donated his knowledge about draw.io. Since IntelliJ is a jetbrains project and jetbrains switched to Kotlin some time ago, he switched to Kotlin as langauge for the plugin.
Kotlin is a modern language which adds quite a few new features and shortcuts.
Java Code can be easily transformed to Kotlin through the IntelliJ IDE (
Convert Java File to Kotlin file).
In addition, the starter template für new plugins is written in Kotlin and thus it is expected that the future will bring more plugins written in Kotlin.
Contributors might have to learn the details of Kotlin wich might result in code which is not perfect Kotlin code.
Since Kotlin is a relative new language, it seems to be harder to find code examples written in Kotlin.
For the main code, this seems to be not a big deal, since you can convert Java to Kotlin (even automatically in Intellij via
Convert Java File to Kotlin file).
But for the Groovy DSL, this might be more of a problem.
7.2. ADR 02: Test-Framework
For testing, we need a test-framework.
We start out with Spock as test-framework
JUnit-X vs. Spock
JUnit seems to be the standard test-framework for Java or Kotlin development. However, Spock seems to be more powerful and lets us use the Behaviour-Driven-Development approach.
With Spock, we add Groovy as additional language to the project. This raises the complexity, and we have to see if this is worth it. Should we notice that we need another test-framework, we can install it as additional one and still keep the Spock tests.
8. Quality Requirements
8.1. Quality Tree
8.2. Quality Scenarios
9. Risks and Technical Debts
no documented risks or technical debts yets.