Software Architecture Documentation Starter with arc42 and C4 Model

Inhalt

• Quick Start
• Techniques & Technologies
  • Documentation
  • Architecture Modeling
  • Tooling & Automation
• Prerequisites
  • Install adr-tools and adjust the ADR template
    • Migrate the generated markdown based decisions with docToolchain
• Build the software architecture documentation
  • Available Commands
• Appendix A: Manual Setup (without dtcw)
  • Generate the PlantUML diagrams from the Structurizr DSL
• License
• Contributing

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.

Step-by-step video tutorial

Check out the deployed example HTML build provided on GitHub Pages.

Quick Start

Get started in 3 simple steps:

# 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 Build the software architecture documentation

Techniques & Technologies

Documentation

arc42	Structure template for software architecture documentation
AsciiDoc	Markup format for writing documentation
Asciidoctor	Processor to generate HTML, PDF and other formats

Architecture Modeling

C4 Model	Abstraction-first approach to diagramming software architecture
Structurizr DSL	DSL to describe C4 models as code
Structurizr CLI	CLI to export PlantUML diagrams from Structurizr DSL

Tooling & Automation

docToolchain	Automation for generating documentation
Kroki	Diagram generation service
adr-tools	Generate and manage Architecture Decision Records (ADRs)
Technical Debt Records	Record and track technical debts (TDRs)

Tip	For more tech inspiration take a look at the Documentation as Code Technology Radar.

Prerequisites

Important

If you don’t plan to use the 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.

1. Install adr-tools

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

3. Replace the content of the template.md file with the content of the 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.

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

Build the software architecture documentation

Available Commands

docToolchain provides the following commands via the ./dtcw wrapper script:

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 kroki.io instance to generate the diagrams. For your own documentation, replace the references to kroki.io with your own kroki instance.

Appendix A: 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

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

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