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: 27 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 

          
:icons: font

:toc: left

:toclevels: 3

:toc-title: Inhalt



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



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



Get more details in the https://www.youtube.com/watch?v=TLcUISoEn2s[Step-by-step video tutorial] available on YouTube.



== Quick Start



Get started in 3 simple steps:



[source, bash]

----

# 1. Generate diagrams from C4 model

./dtcw exportStructurizr



# 2. Build HTML documentation

./dtcw generateHTML



# 3. Open the result

open build/html5/internet-banking-system.html

----



For more details, see <>



== Techniques & Technologies



=== Documentation



[cols="1,3"]

|===

|https://arc42.org/[arc42] |Structure template for software architecture documentation

|https://asciidoc.org/[AsciiDoc] |Markup format for writing documentation

|https://asciidoctor.org/[Asciidoctor] |Processor to generate HTML, PDF and other formats

|===



=== Architecture Modeling



[cols="1,3"]

|===

|https://c4model.com/[C4 Model] |Abstraction-first approach to diagramming software architecture

|https://structurizr.com/dsl[Structurizr DSL] |DSL to describe C4 models as code

|https://github.com/structurizr/cli[Structurizr CLI] |CLI to export PlantUML diagrams from Structurizr DSL

|===



=== Tooling & Automation



[cols="1,3"]

|===

|https://doctoolchain.org[docToolchain] |Automation for generating documentation

|https://kroki.io[Kroki] |Diagram generation service

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

|https://www.workingsoftware.dev/technical-debt-records/[Technical Debt Records] |Record and track technical debts (TDRs)

|===



TIP: 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



=== Available Commands



https://doctoolchain.org/docToolchain/[docToolchain] provides the following commands via the `./dtcw` wrapper script:



[cols="2,3"]

|===

|Command |Description



|`./dtcw exportStructurizr`

|Generate PlantUML diagrams from the C4 Model (Structurizr DSL)



|`./dtcw generateHTML`

|Generate HTML documentation



|`./dtcw generatePDF`

|Generate PDF documentation



|`./dtcw generateSite`

|Generate documentation as Microsite



|`./dtcw exportMarkdown`

|Convert Markdown ADRs to AsciiDoc

|===



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.



[appendix]

== Manual Setup (without dtcw)



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/v2025.11.09/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

----



== License



This project is open source. Feel free to use it as a starting point for your own software architecture documentation.



== Contributing



Contributions are welcome! Please feel free to submit issues or pull requests.