Software Architecture Documentation Example with arc42 and C4 Model

This example shows how to use arc42 in combination with the C4 model with the Documentation as Code technique.

It shows how to use the techniques described in The ultimate Guide to Software Architecture Documentation.

Technologies involved:

• arc42 to get the structure for the software architecture documentation

• C4 Model an "abstraction-first" approach to diagramming software architecture, based upon abstractions that reflect how software architects and developers think about and build software.

• Structurizr DSL to describe the C4 Model of the software system

• Structurizr CLI a command line utility for Structurizr to export the PlantUML diagrams from the C4 Model described in the Structurizr DSL

• AsciiDoc as format to write the software architecture documentation

• docToolchain to generate the representations of the software architecture documentation written in asciidoc. docToolchain makes use of Asciidoctor.

• kroki to generate diagrams

Prerequisites

• Download the structurizr-cli, unzip and move it into ./bin/structurizr-cli

curl --show-error --location https://github.com/structurizr/cli/releases/download/v1.25.0/structurizr-cli-1.25.0.zip  -o tmp.zip && unzip -d bin/structurizr-cli/. tmp.zip && rm tmp.zip

• Generate the diagrams from the structurizr workspace model

./bin/structurizr-cli/structurizr.sh export -w bank.dsl -format plantuml/structurizr -output documentation/diagrams

Generate the software architecture documentation representations

Note	these examples use the public kroki.io instance to generate the diagrams. For your own documentation, replace the references to kroki.io with your own kroki instance.

• Generate the documentation as single HTML file

./dtcw generateHTML

Generate the documentation as PDF representation

./dtcw generatePDF

• Generate the documentation as Microsite

./dtcw generateSite