Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bitsmuggler/arc42-c4-software-architecture-documentation-example

This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique.
https://github.com/bitsmuggler/arc42-c4-software-architecture-documentation-example

arc42 c4 c4-model docsascode documentation-as-code

Last synced: 17 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
: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

----