Data

Tools

Indexes

Applications

Experiments

Awesome

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

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: 7 months 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 Starter with arc42 and C4 Model



image::banner.png[]



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].



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 https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/[example HTML build] provided on GitHub Pages.



Go through the following steps:



. <>

. <>

.. <>

.. <>



== Technologies



* 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://asciidoctor.org/[Asciidoctor] to generate the representations of the software architecture documentation written in AsciiDoc.

* https://doctoolchain.org[docToolchain] to automate the generation of the software architecture documentation.

* https://kroki.io[Kroki] to generate diagrams

* https://github.com/npryce/adr-tools[adr-tools] to generate and manage Architecture Decision Records (ADRs)

* https://www.workingsoftware.dev/technical-debt-records/[Technical Debt Records] to record technical debts (TDRs)



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



== Prerequisites



[IMPORTANT]

====

If you don't plan to use the https://github.com/npryce/adr-tools[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.



. Install https://github.com/npryce/adr-tools[adr-tools]

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

. Replace the content of the `template.md` file with the content of the link:./adr-template.md[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.



[source, bash]

----

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

----



== Build the software architecture documentation



=== Generate PlantUML Diagrams from the C4 (Structurizr) Model



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

----



=== 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

----



=== 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*



[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/{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



[source, bash]

----

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

----