{"id":14529555,"url":"https://github.com/bitsmuggler/arc42-c4-software-architecture-documentation-example","last_synced_at":"2026-05-18T11:16:18.159Z","repository":{"id":68113161,"uuid":"559197192","full_name":"bitsmuggler/arc42-c4-software-architecture-documentation-example","owner":"bitsmuggler","description":"This example shows how you can use arc42 in combination with the C4 model and the Documentation as Code technique.","archived":false,"fork":false,"pushed_at":"2025-05-31T08:39:08.000Z","size":4877,"stargazers_count":146,"open_issues_count":2,"forks_count":27,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-31T19:53:11.209Z","etag":null,"topics":["arc42","c4","c4-model","docsascode","documentation-as-code"],"latest_commit_sha":null,"homepage":"https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsmuggler.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-29T11:13:25.000Z","updated_at":"2025-05-31T08:37:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"e2a070c3-c81b-45e5-bd2d-b6a9714b1b53","html_url":"https://github.com/bitsmuggler/arc42-c4-software-architecture-documentation-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bitsmuggler/arc42-c4-software-architecture-documentation-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsmuggler%2Farc42-c4-software-architecture-documentation-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsmuggler%2Farc42-c4-software-architecture-documentation-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsmuggler%2Farc42-c4-software-architecture-documentation-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsmuggler%2Farc42-c4-software-architecture-documentation-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsmuggler","download_url":"https://codeload.github.com/bitsmuggler/arc42-c4-software-architecture-documentation-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsmuggler%2Farc42-c4-software-architecture-documentation-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273213652,"owners_count":25065058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arc42","c4","c4-model","docsascode","documentation-as-code"],"created_at":"2024-09-05T00:01:00.756Z","updated_at":"2026-05-18T11:16:18.153Z","avatar_url":"https://github.com/bitsmuggler.png","language":"Shell","funding_links":[],"categories":["Documentation Types"],"sub_categories":["Architectural Documentation"],"readme":":icons: font\n:toc: left\n:toclevels: 3\n:toc-title: Inhalt\n\n= Software Architecture Documentation Starter with arc42 and C4 Model\n\nimage::banner.png[]\n\nThis example shows how to use https://arc42.org/[arc42] in combination with the https://c4model.com/[C4 model] with the Documentation as Code technique.\n\nIt 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].\n\n\nCheck out the deployed https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/[example HTML build] provided on GitHub Pages.\n\nGet more details in the https://www.youtube.com/watch?v=TLcUISoEn2s[Step-by-step video tutorial] available on YouTube.\n\n== Quick Start\n\nGet started in 3 simple steps:\n\n[source, bash]\n----\n# 1. Generate diagrams from C4 model\n./dtcw exportStructurizr\n\n# 2. Build HTML documentation\n./dtcw generateHTML\n\n# 3. Open the result\nopen build/html5/internet-banking-system.html\n----\n\nFor more details, see \u003c\u003cBuild the software architecture documentation\u003e\u003e\n\n\n== Techniques \u0026 Technologies\n\n=== Documentation\n\n[cols=\"1,3\"]\n|===\n|https://arc42.org/[arc42] |Structure template for software architecture documentation\n|https://asciidoc.org/[AsciiDoc] |Markup format for writing documentation\n|https://asciidoctor.org/[Asciidoctor] |Processor to generate HTML, PDF and other formats\n|===\n\n=== Architecture Modeling\n\n[cols=\"1,3\"]\n|===\n|https://c4model.com/[C4 Model] |Abstraction-first approach to diagramming software architecture\n|https://structurizr.com/dsl[Structurizr DSL] |DSL to describe C4 models as code\n|https://github.com/structurizr/cli[Structurizr CLI] |CLI to export PlantUML diagrams from Structurizr DSL\n|===\n\n=== Tooling \u0026 Automation\n\n[cols=\"1,3\"]\n|===\n|https://doctoolchain.org[docToolchain] |Automation for generating documentation\n|https://kroki.io[Kroki] |Diagram generation service\n|https://github.com/npryce/adr-tools[adr-tools] |Generate and manage Architecture Decision Records (ADRs)\n|https://www.workingsoftware.dev/technical-debt-records/[Technical Debt Records] |Record and track technical debts (TDRs)\n|===\n\nTIP: For more tech inspiration take a look at the https://www.workingsoftware.dev/documentation-as-code-tools[Documentation as Code Technology Radar].\n\n== Prerequisites\n\n[IMPORTANT]\n====\nIf 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.\n====\n\n=== Install adr-tools and adjust the ADR template\n\nThe ADR template is based on Markdown and the ADR chapters must be adapted to the chapter levels of the arc42 template.\n\n. Install https://github.com/npryce/adr-tools[adr-tools]\n. Get the path of the adr template of the adr-tools via `adr config`\n. Replace the content of the `template.md` file with the content of the link:./adr-template.md[adr-template.md] file of this repository.\n\n==== Migrate the generated markdown based decisions with docToolchain\n\nIf you have already generated ADRs with the adr-tools, you can migrate them to the AsciiDoc format with the following steps.\n\n[source, bash]\n----\n./dtcw exportMarkdown \u0026\u0026 cp ./build/adrs/*.adoc ./documentation/adrs/\n----\n\n== Build the software architecture documentation\n\n=== Available Commands\n\nhttps://doctoolchain.org/docToolchain/[docToolchain] provides the following commands via the `./dtcw` wrapper script:\n\n[cols=\"2,3\"]\n|===\n|Command |Description\n\n|`./dtcw exportStructurizr`\n|Generate PlantUML diagrams from the C4 Model (Structurizr DSL)\n\n|`./dtcw generateHTML`\n|Generate HTML documentation\n\n|`./dtcw generatePDF`\n|Generate PDF documentation\n\n|`./dtcw generateSite`\n|Generate documentation as Microsite\n\n|`./dtcw exportMarkdown`\n|Convert Markdown ADRs to AsciiDoc\n|===\n\nNOTE: These examples use the public https://kroki.io[kroki.io] instance to generate the diagrams.\nFor your own documentation, replace the references to kroki.io with your own kroki instance.\n\n[appendix]\n== Manual Setup (without dtcw)\n\nIf you want to build everything without the `./dtcw` script, you can use the following commands.\n\n=== Generate the PlantUML diagrams from the Structurizr DSL\n\n*With the Structurizr CLI via Docker Image*\n\n[source, bash]\n----\ndocker run -it --rm -v $PWD:/usr/local/structurizr structurizr/cli export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams\n----\n\n*With a local installed Structurizr CLI*\n\nDownload the https://github.com/structurizr/cli/releases[structurizr-cli], unzip and move it into `./bin/structurizr-cli` or use the latest Docker Image\n\n[source, bash]\n----\ncurl --show-error --location https://github.com/structurizr/cli/releases/download/v2025.11.09/structurizr-cli.zip  -o tmp.zip \u0026\u0026 mkdir -p bin/structurizr-cli \u0026\u0026 unzip -d bin/structurizr-cli tmp.zip \u0026\u0026 rm tmp.zip\n----\n\nGenerate the diagrams from the structurizr workspace model\n\n[source, bash]\n----\n./bin/structurizr-cli/structurizr.sh export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams\n----\n\n== License\n\nThis project is open source. Feel free to use it as a starting point for your own software architecture documentation.\n\n== Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsmuggler%2Farc42-c4-software-architecture-documentation-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsmuggler%2Farc42-c4-software-architecture-documentation-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsmuggler%2Farc42-c4-software-architecture-documentation-example/lists"}