arc42-c4-software-architecture-documentation-example

arc42-c4-software-architecture-documentation-example copied to clipboard

:selected-version: 1.25.0 :icons: font

= Software Architecture Documentation Example with arc42 and C4 Model

This example shows how to use https://arc42.org/[arc42] in combination with the https://c4model.com/[C4 model] with the Documentation as Code technique.

It shows how to use the techniques described in https://www.workingsoftware.dev/software-architecture-documentation-the-ultimate-guide/[The ultimate Guide to Software Architecture Documentation].

Check out the deployed https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/[HTML build] provided on GitHub Pages.

Technologies involved:

• https://arc42.org/[arc42] to get the structure for the software architecture documentation
• https://c4model.com/[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.
• https://structurizr.com/dsl[Structurizr DSL] to describe the https://c4model.com/[C4 Model] of the software system
• https://github.com/structurizr/cli[Structurizr CLI] a command line utility for Structurizr to export the https://plantuml.com/[PlantUML] diagrams from the C4 Model described in the Structurizr DSL
• https://asciidoc.org/[AsciiDoc] as format to write the software architecture documentation
• https://doctoolchain.org[docToolchain] to generate the representations of the software architecture documentation written in https://asciidoc.org/[AsciiDoc]. docToolchain makes use of https://docs.asciidoctor.org/asciidoctor[Asciidoctor].
• https://kroki.io[Kroki] to generate diagrams
• https://github.com/npryce/adr-tools[adr-tools] to generate and manage Architecture Decision Records (ADRs)

For more tech inspiration take a look at the https://www.workingsoftware.dev/documentation-as-code-tools[Documentation as Code Technology Radar]

== Prerequisites

=== Generate PlantUML Diagrams from the C4 Model

==== With the Structurizr CLI via Docker Image

[source, bash]

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 https://github.com/structurizr/cli/releases[structurizr-cli], unzip and move it into ./bin/structurizr-cli or use the latest Docker Image

[source, bash]

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

[source, bash]

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

==== With the docToolchain

https://doctoolchain.org/docToolchain/[docToolchain] uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.

[source, bash]

./dtcw exportStructurizr

== Migrate markdown based ADRs from adr-tools to AsciiDoc

=== Install and configure adr-tools

. Install https://github.com/npryce/adr-tools[adr-tools] . Configure the adr template with the following header config

[source, bash]

adr config

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

[source, markdown]

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

[source, bash]

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

== Generate the software architecture documentation representations

NOTE: these examples use the public https://kroki.io[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

[source, bash]

./dtcw generateHTML

Generate the documentation as PDF representation

[source, bash]

./dtcw generatePDF

Generate the documentation as Microsite

[source, bash]

./dtcw generateSite