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.

Check out the deployed HTML build provided on GitHub Pages.

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

• https://docker.com to run structurizr diagrams generator

For more tech inspiration take a look at the Documentation as Code Technology Radar

Prerequisites

Install docToolchain

• [docToolchain tutorial](https://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/010_Install.html)

• Configure path to structurizr main dsl file in the docToolchainConfig.groovy

Generate PlantUML from the structurizr using the docToolchain

docToolchain uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.

./dtcw.ps1 exportStructurizr

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 HTML representation

./dtcw.ps1 generateHTML

Generate the documentation as PDF representation

./dtcw.ps1 generatePDF

Generate the documentation as Microsite

./dtcw.ps1 generateSite