Distributed Application Architecture Patterns

2.3 Technologies

This section details the technologies used to create the diagrams and the website.

2.3.1 Diagrams

The diagrams are constructed using PlantUML, a text-based diagramming tool that allows for easy version control and global styling. Joshi [5] already proved its validity for this use case. It presents some challenges, as its lack of granularity for controlling layout and limited style options are most visible with big, prominent designs, such as those in this work.

The biggest sore point is activity diagrams, which do not allow any control over the layout of the elements, so even simple diagrams can become cluttered and hard to read. While PlantUML does have tools to achieve the layout needed, to access them, one has to switch to a different diagram type, which makes start and end nodes inaccessible. One workaround is to design it as a state diagram with a hide empty description statement, such as fig. 29, which produces visually identical output, albeit requiring more manual work.

Another common issue is alignment. While PlantUML generally places elements on a grid, it is relatively easy to be left with angled, instead of perpendicular, lines, especially with nested elements. One possible solution is to strategically apply norank to arrows, which relaxes some constraints on the layout and may help straighten out the rest, such as in the aforementioned fig. 29. Switching to a left to right direction can help with making horizontal forks balanced, such as in fig. 12.

However, eventually, the last option is to give in and change the design to fit the tool or accept the limitations, such as with fig. 24. Some examples are the inability to style certain elements, such as some types of padding, arrowheads, or line thickness being inconsistently applied. Other examples are documented in § 2.4.

Other tools exist, such as Mermaid, but none seem to provide the same level of features and control as PlantUML.

2.3.2 Website

To account for dual-generation of this work – one into a PDF and one into a website – the text is written in Markdown with YAML front matter for custom metadata, such as subtitles. The LaTeX Markdown package by Novotný [30] is used to translate them for LaTeX with custom renderers to read the front matter and generate the subtitles accordingly.

Rendering HTML is a bit more tricky. One option is to use Pandoc with the chunkedhtml output [31, p. 147], but that only has support for document-level metadata. To account for that, the front matter is extracted with Python into a JSON file before processing with Pandoc, for later use with Eleventy, a static site generator tool.

Styling is done with Tailwind CSS and it is hosted on GitHub Pages. The website has support for mobile devices and dark mode.