- Notifications
You must be signed in to change notification settings - Fork30
This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique.
bitsmuggler/arc42-c4-software-architecture-documentation-example
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This example shows how to usearc42 in combination with theC4 model with the Documentation as Code technique.
It shows how to use the techniques described inThe 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 deployedexample HTML build provided on GitHub Pages.
Go through the following steps:
arc42 to get the structure for the software architecture documentation
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.
Structurizr DSL to describe theC4 Model of the software system
Structurizr CLI a command line utility for Structurizr to export thePlantUML diagrams from the C4 Model described in the Structurizr DSL
AsciiDoc as format to write the software architecture documentation
Asciidoctor to generate the representations of the software architecture documentation written in AsciiDoc.
docToolchain to automate the generation of the software architecture documentation.
Kroki to generate diagrams
adr-tools to generate and manage Architecture Decision Records (ADRs)
Technical Debt Records to record technical debts (TDRs)
For more tech inspiration take a look at theDocumentation as Code Technology Radar.
Important | If you don’t plan to use theadr-tools, you can skip this step. Please make sure that Chapter 09 Architecture Decisions does not contain any references to the ADRs. |
The ADR template is based on Markdown and the ADR chapters must be adapted to the chapter levels of the arc42 template.
Installadr-tools
Get the path of the adr template of the adr-tools via
adr configReplace the content of the
template.mdfile with the content of theadr-template.md file of this repository.
docToolchain uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.
./dtcw exportStructurizr
Note | these examples use the publickroki.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
./dtcw generateHTML
Generate the documentation as PDF representation
./dtcw generatePDF
Generate the documentation as Microsite
./dtcw generateSite
If you want to build everything without the./dtcw script, you can use the following commands.
With the Structurizr CLI via Docker Image
docker run -it --rm -v$PWD:/usr/local/structurizr structurizr/cliexport -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
With a local installed Structurizr CLI
Download thestructurizr-cli, unzip and move it into
./bin/structurizr-clior use the latest Docker Image
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.zipGenerate the diagrams from the structurizr workspace model
./bin/structurizr-cli/structurizr.shexport -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagramsAbout
This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique.
Topics
Resources
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Releases
Packages0
Uh oh!
There was an error while loading.Please reload this page.