Skip to content

Commit f295cc0

Browse files
bitsmugglerbitsmuggler
committed
- docToolChain Updated (3.4.1 -> 3.4.2)
- README.adoc refactored - Newest bank.dsl included
1 parent 88188ea commit f295cc0

File tree

3 files changed

+93
-73
lines changed

3 files changed

+93
-73
lines changed

‎README.adoc‎

Lines changed: 80 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
:selected-version: 1.25.0
21
:icons: font
2+
:toc: left
3+
:toclevels: 3
4+
:toc-title: Inhalt
35

46
= Software Architecture Documentation Starter with arc42 and C4 Model
57

@@ -9,32 +11,60 @@ This example shows how to use https://arc42.org/[arc42] in combination with the
911

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

12-
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
14+
video::TLcUISoEn2s[youtube, title="Step-by-step video tutorial"]
1315

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

16-
Go through the following steps:
18+
== Quick Start
1719

18-
. <<Prerequisites>>
19-
. <<Build the software architecture documentation>>
20-
.. <<Generate PlantUML Diagrams from the C4 (Structurizr) Model>>
21-
.. <<Generate the software architecture documentation representations>>
20+
Get started in 3 simple steps:
2221

22+
[source, bash]
23+
----
24+
# 1. Generate diagrams from C4 model
25+
./dtcw exportStructurizr
26+
27+
# 2. Build HTML documentation
28+
./dtcw generateHTML
29+
30+
# 3. Open the result
31+
open build/html5/internet-banking-system.html
32+
----
33+
34+
For more details, see <<Build the software architecture documentation>>
35+
36+
37+
== Techniques & Technologies
2338

24-
== Technologies
39+
=== Documentation
2540

26-
* https://arc42.org/[arc42] to get the structure for the software architecture documentation
27-
* 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.
28-
* https://structurizr.com/dsl[Structurizr DSL] to describe the https://c4model.com/[C4 Model] of the software system
29-
* 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
30-
* https://asciidoc.org/[AsciiDoc] as format to write the software architecture documentation
31-
* https://asciidoctor.org/[Asciidoctor] to generate the representations of the software architecture documentation written in AsciiDoc.
32-
* https://doctoolchain.org[docToolchain] to automate the generation of the software architecture documentation.
33-
* https://kroki.io[Kroki] to generate diagrams
34-
* https://github.com/npryce/adr-tools[adr-tools] to generate and manage Architecture Decision Records (ADRs)
35-
* https://www.workingsoftware.dev/technical-debt-records/[Technical Debt Records] to record technical debts (TDRs)
41+
[cols="1,3"]
42+
|===
43+
|https://arc42.org/[arc42] |Structure template for software architecture documentation
44+
|https://asciidoc.org/[AsciiDoc] |Markup format for writing documentation
45+
|https://asciidoctor.org/[Asciidoctor] |Processor to generate HTML, PDF and other formats
46+
|===
3647

37-
For more tech inspiration take a look at the https://www.workingsoftware.dev/documentation-as-code-tools[Documentation as Code Technology Radar].
48+
=== Architecture Modeling
49+
50+
[cols="1,3"]
51+
|===
52+
|https://c4model.com/[C4 Model] |Abstraction-first approach to diagramming software architecture
53+
|https://structurizr.com/dsl[Structurizr DSL] |DSL to describe C4 models as code
54+
|https://github.com/structurizr/cli[Structurizr CLI] |CLI to export PlantUML diagrams from Structurizr DSL
55+
|===
56+
57+
=== Tooling & Automation
58+
59+
[cols="1,3"]
60+
|===
61+
|https://doctoolchain.org[docToolchain] |Automation for generating documentation
62+
|https://kroki.io[Kroki] |Diagram generation service
63+
|https://github.com/npryce/adr-tools[adr-tools] |Generate and manage Architecture Decision Records (ADRs)
64+
|https://www.workingsoftware.dev/technical-debt-records/[Technical Debt Records] |Record and track technical debts (TDRs)
65+
|===
66+
67+
TIP: For more tech inspiration take a look at the https://www.workingsoftware.dev/documentation-as-code-tools[Documentation as Code Technology Radar].
3868

3969
== Prerequisites
4070

@@ -62,46 +92,39 @@ If you have already generated ADRs with the adr-tools, you can migrate them to t
6292

6393
== Build the software architecture documentation
6494

65-
=== Generate PlantUML Diagrams from the C4 (Structurizr) Model
95+
=== Available Commands
6696

67-
https://doctoolchain.org/docToolchain/[docToolchain] uses the Structurizr CLI to generate the PlantUML diagrams from the C4 Model described in the Structurizr DSL.
97+
https://doctoolchain.org/docToolchain/[docToolchain] provides the following commands via the `./dtcw` wrapper script:
6898

69-
[source, bash]
70-
----
71-
./dtcw exportStructurizr
72-
----
99+
[cols="2,3"]
100+
|===
101+
|Command |Description
73102

74-
=== Generate the software architecture documentation representations
103+
|`./dtcw exportStructurizr`
104+
|Generate PlantUML diagrams from the C4 Model (Structurizr DSL)
75105

76-
NOTE: these examples use the public https://kroki.io[kroki.io] instance to generate the diagrams.
77-
For your own documentation, replace the references to kroki.io with your own kroki instance.
106+
|`./dtcw generateHTML`
107+
|Generate HTML documentation
78108

79-
Generate the documentation as HTML representation
109+
|`./dtcw generatePDF`
110+
|Generate PDF documentation
80111

81-
[source, bash]
82-
----
83-
./dtcw generateHTML
84-
----
85-
86-
Generate the documentation as PDF representation
87-
88-
[source, bash]
89-
----
90-
./dtcw generatePDF
91-
----
112+
|`./dtcw generateSite`
113+
|Generate documentation as Microsite
92114

93-
Generate the documentation as Microsite
115+
|`./dtcw exportMarkdown`
116+
|Convert Markdown ADRs to AsciiDoc
117+
|===
94118

95-
[source, bash]
96-
----
97-
./dtcw generateSite
98-
----
119+
NOTE: These examples use the public https://kroki.io[kroki.io] instance to generate the diagrams.
120+
For your own documentation, replace the references to kroki.io with your own kroki instance.
99121

100-
=== Appendix
122+
[appendix]
123+
== Manual Setup (without dtcw)
101124

102125
If you want to build everything without the `./dtcw` script, you can use the following commands.
103126

104-
==== Generate the PlantUML diagrams from the Structurizr DSL
127+
=== Generate the PlantUML diagrams from the Structurizr DSL
105128

106129
*With the Structurizr CLI via Docker Image*
107130

@@ -116,12 +139,20 @@ docker run -it --rm -v $PWD:/usr/local/structurizr structurizr/cli export -w doc
116139

117140
[source, bash]
118141
----
119-
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
142+
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
120143
----
121144

122145
* Generate the diagrams from the structurizr workspace model
123146

124147
[source, bash]
125148
----
126149
./bin/structurizr-cli/structurizr.sh export -w documentation/bank.dsl -format plantuml/structurizr -output documentation/diagrams
127-
----
150+
----
151+
152+
== License
153+
154+
This project is open source. Feel free to use it as a starting point for your own software architecture documentation.
155+
156+
== Contributing
157+
158+
Contributions are welcome! Please feel free to submit issues or pull requests.

‎documentation/bank.dsl‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* This is a combined version of the following workspaces, with automatic layout enabled:
2+
* This is a combined version of the following workspaces:
33
*
44
* - "Big Bank plc - System Landscape" (https://structurizr.com/share/28201/)
55
* - "Big Bank plc - Internet Banking System" (https://structurizr.com/share/36141/)
@@ -61,7 +61,7 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
6161
accountsSummaryController -> mainframeBankingSystemFacade "Uses"
6262
resetPasswordController -> securityComponent "Uses"
6363
resetPasswordController -> emailComponent "Uses"
64-
securityComponent -> database "Reads from and writes to" "SQL/TCP"
64+
securityComponent -> database "Reads from and writes to" "JDBC"
6565
mainframeBankingSystemFacade -> mainframe "Makes API calls to" "XML/HTTPS"
6666
emailComponent -> email "Sends e-mail using"
6767

@@ -146,10 +146,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
146146
email
147147
}
148148
autoLayout
149-
description "The system context diagram for the Internet Banking System."
150-
properties {
151-
structurizr.groups false
152-
}
153149
}
154150

155151
container internetBankingSystem "Containers" {
@@ -163,7 +159,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
163159
database
164160
}
165161
autoLayout
166-
description "The container diagram for the Internet Banking System."
167162
}
168163

169164
component apiApplication "Components" {
@@ -175,12 +170,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
175170
resetPasswordController emailComponent
176171
}
177172
autoLayout
178-
description "The component diagram for the API Application."
179-
}
180-
181-
image mainframeBankingSystemFacade "MainframeBankingSystemFacade" {
182-
image https://raw.githubusercontent.com/structurizr/examples/main/dsl/big-bank-plc/internet-banking-system/mainframe-banking-system-facade.png
183-
title "[Code] Mainframe Banking System Facade"
184173
}
185174

186175
dynamic apiApplication "SignIn" "Summarises how the sign in feature works in the single-page application." {
@@ -191,7 +180,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
191180
securityComponent -> signinController "Returns true if the hashed password matches"
192181
signinController -> singlePageApplication "Sends back an authentication token to"
193182
autoLayout
194-
description "Summarises how the sign in feature works in the single-page application."
195183
}
196184

197185
deployment internetBankingSystem "Development" "DevelopmentDeployment" {
@@ -202,7 +190,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
202190
developerDatabaseInstance
203191
}
204192
autoLayout
205-
description "An example development deployment scenario for the Internet Banking System."
206193
}
207194

208195
deployment internetBankingSystem "Live" "LiveDeployment" {
@@ -215,7 +202,6 @@ workspace "Big Bank plc" "This is an example workspace to illustrate the key fea
215202
liveSecondaryDatabaseInstance
216203
}
217204
autoLayout
218-
description "An example live deployment scenario for the Internet Banking System."
219205
}
220206

221207
styles {

‎dtcw‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ set -o pipefail
1212

1313
# See https://github.com/docToolchain/docToolchain/releases for available versions.
1414
# Set DTC_VERSION to "latest" to get the latest, yet unreleased version.
15-
: "${DTC_VERSION:=3.4.1}"
15+
: "${DTC_VERSION:=3.4.2}"
1616

1717
# if not set, public docker hub is used
1818
: "${DTC_DOCKER_PREFIX:=}"
@@ -37,7 +37,10 @@ export DTC_PROJECT_BRANCH
3737
export DTC_HEADLESS
3838

3939
# Options passed to docToolchain
40-
DTC_OPTS="${DTC_OPTS:-} -PmainConfigFile=${DTC_CONFIG_FILE} --warning-mode=none --no-daemon -Dfile.encoding=UTF-8 "
40+
DTC_OPTS="${DTC_OPTS:-} --warning-mode=none --no-daemon -Dfile.encoding=UTF-8 "
41+
if [ -n "${DTC_CONFIG_FILE}" ]; then
42+
DTC_OPTS="${DTC_OPTS} -PmainConfigFile=${DTC_CONFIG_FILE}"
43+
fi
4144

4245
# Here you find the project
4346
GITHUB_PROJECT_URL=https://github.com/docToolchain/docToolchain
@@ -487,7 +490,7 @@ assert_java_version_supported() {
487490
java_version=$(echo "$java_version" | awk -F '"' '/version/ {print $0}' | head -1 | cut -d'"' -f2)
488491
major_version=$(echo "$java_version" | sed '/^1\./s///' | cut -d'.' -f1)
489492

490-
if [ "${major_version}" -ge 11 ] && [ "${major_version}" -le 17 ]; then
493+
if [ "${major_version}" -eq 17 ]; then
491494
echo "Using Java ${java_version} [${JAVA_CMD}]"
492495
return
493496
fi
@@ -498,8 +501,8 @@ assert_java_version_supported() {
498501

499502
java_help_and_die() {
500503
printf "%s\n" \
501-
"docToolchain supports Java versions 11, 14, or 17 (preferred). In case one of those" \
502-
"Java versions is installed make sure 'java' is found with your PATH environment" \
504+
"docToolchain supports Java version 17 only. In case that" \
505+
"Java version is installed make sure 'java' is found with your PATH environment" \
503506
"variable. As alternative you may provide the location of your Java installation" \
504507
"with JAVA_HOME." \
505508
"" \
@@ -516,7 +519,7 @@ java_help_and_die() {
516519
fi
517520
# TODO: This will break when we change Java version
518521
printf "%s\n" \
519-
" $ sdk install java 17.0.7-tem" \
522+
" $ sdk install java 17.0.14-tem" \
520523
"" \
521524
"If you prefer not to install Java on your host, you can run docToolchain in a" \
522525
"docker container. For this case dtcw provides the 'docker' execution environment." \
@@ -602,7 +605,7 @@ how_to_install_doctoolchain() {
602605
" \$ sdk install doctoolchain ${version}" \
603606
"" \
604607
"Note that running docToolchain in 'local' or 'sdk' environment needs a" \
605-
"Java runtime (major version 11, 14, or 17) installed on your host." \
608+
"Java runtime major version 17 installed on your host." \
606609
"" \
607610
"3. 'docker': pull the docToolchain image and execute docToolchain in a container environment." \
608611
"" \
@@ -684,4 +687,4 @@ DTC_HOME="${DTC_ROOT}/docToolchain-${DTC_VERSION}"
684687
# Directory for local Java installation
685688
DTC_JAVA_HOME="${DTC_ROOT}/jdk"
686689

687-
main "$@"
690+
main "$@"

0 commit comments

Comments
 (0)