About arc42

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 .png or .svg image. 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

1

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.

2

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

3

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)[1]. 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

TODO

let’s use the C4 PlantUML syntax here!

3.2. Technical Context

TODO

3.2.1. draw.io interface

The draw.io interface is messages based and described in the support article Embed Mode.

Example can be found at

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

rts1
Figure 1. 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. Intellij sends project and file to the DiagramsEditorProvider's accept method. 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. If accept() returns a true, IntelliJ will create and Display the DiagramsEditor.

5.2. RTS 02: Init WebView

In this scenario, we will see how the basic communication between the JavaScript based draw.io and the Kotlin based Plugin works

rts2
Figure 2. Init WebView

6. RTS 03: Autosave

rts3
Figure 3. Init WebView

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

Status Date Decided by

decided

07.11.20

rdmueller

7.1.1. Problem

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.

7.1.2. Decision

This plugin uses Kotlin as programming language.

7.1.3. Alternatives

Groovy

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.

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.

Kotlin

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 (Code → 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.

7.1.4. Consequences

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 Code → Convert Java File to Kotlin file). But for the Groovy DSL, this might be more of a problem.

7.2. ADR 02: Test-Framework

Status Date Decided by

decided

07.11.20

rdmueller

7.2.1. Problem

For testing, we need a test-framework.

7.2.2. Decision

We start out with Spock as test-framework

7.2.3. Alternatives

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.

7.2.4. Consequences

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

TODO:

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

8.1. Quality Tree

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

8.2. Quality Scenarios

Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

  • Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

  • Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

9. Risks and Technical Debts

no documented risks or technical debts yets.

10. Glossary

Term Alias Definition

diagrams.net

draw.io

open source, online, desktop and container deployable diagramming software
see also this blog post

JCEF

a Java port for CEF

CEF

Chromium Embedded Framework

a framework/technology to embed the well-known Chromium browser in other applications.
1. see the JetBraint Platform blog post from July 15, 2020: https://blog.jetbrains.com/platform/2020/07/javafx-and-jcef-in-the-intellij-platform/