Software Architecture Documentation Starter 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.

If you’re looking for a step-by-step video on how to use this starter project, you can find it on Youtube here: https://www.youtube.com/watch?v=TLcUISoEn2s

Check out the deployed example HTML build provided on GitHub Pages.

Go through the following steps:

1. Prerequisites

2. Build the software architecture documentation

   1. Generate PlantUML Diagrams from the C4 (Structurizr) Model

   2. Generate the software architecture documentation representations

Technologies

• 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

• Asciidoctor to generate the representations of the software architecture documentation written in AsciiDoc.

• docToolchain to automate the generation of the software architecture documentation.

• Kroki to generate diagrams

• adr-tools to generate and manage Architecture Decision Records (ADRs)

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

Prerequisites

Important

If you don’t plan to use the adr-tools, you can skip this step. Please make sure that Chapter 09 Architecture Decisions does not contain any references to the ADRs.

Install adr-tools and adjust the ADR template

The ADR template is based on Markdown and the ADR chapters must be adapted to the chapter levels of the arc42 template.

1. Install adr-tools

2. Get the path of the adr template of the adr-tools via adr config

3. Replace the content of the template.md file with the content of the adr-template.md file of this repository.

Migrate the generated markdown based decisions with docToolchain

If you have already generated ADRs with the adr-tools, you can migrate them to the AsciiDoc format with the following steps.

./dtcw exportMarkdown && cp ./build/adrs/*.adoc ./documentation/adrs/

Build the software architecture documentation

Generate PlantUML Diagrams from the C4 (Structurizr) Model

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

./dtcw 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 generateHTML

Generate the documentation as PDF representation

./dtcw generatePDF

Generate the documentation as Microsite

./dtcw generateSite

Appendix

If you want to build everything without the ./dtcw script, you can use the following commands.

Generate the PlantUML diagrams from the Structurizr DSL

With the Structurizr CLI via Docker Image

docker run -it --rm -v $PWD:/usr/local/structurizr structurizr/cli export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams

With a local installed Structurizr CLI

• Download the structurizr-cli, unzip and move it into ./bin/structurizr-cli or use the latest Docker Image

curl --show-error --location https://github.com/structurizr/cli/releases/download/{selected-version}/structurizr-cli.zip  -o tmp.zip && mkdir -p bin/structurizr-cli && 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 documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams