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

• 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

Generate PlantUML Diagrams from the C4 Model

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/v{selected-version}/structurizr-cli-{selected-version}.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 documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams

With the docToolchain

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

./dtcw exportStructurizr

Migrate markdown based ADRs from adr-tools to AsciiDoc

Install and configure adr-tools

1. Install adr-tools

2. Configure the adr template with the following header config

adr config

Replace the content of the template.md file with the following content:

### TITLE

Date: DATE

#### Status

STATUS

#### Context

The issue motivating this decision, and any context that influences or constrains the decision.

#### Decision

The change that we're proposing or have agreed to implement.

#### Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

Migrate the generated markdown based decisions with the docker-asciidoctor image under Linux

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

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