Software Architecture Documentation

This repository maintains architecture documentation based on arc42, Structurizr C4 DSL, and Architecture Decision Records (ADRs), built via docToolchain and containerized tooling.

---

Prerequisites

• Docker and Docker Compose
• Make, Git, and Bash

No local installation of Java, Gradle, PlantUML, or adr-tools is required on the host system.

---

Quick Start (via make)

The repository provides a Makefile as a single point of access for all frequent build and management commands:

Command	Description
make build	Build complete documentation (HTML + PDF with diagrams and ADRs)
make html	Build single-page HTML document (build/html5/arc42/arc42.html)
make pdf	Build PDF document (build/pdf/arc42/arc42.pdf)
make diagrams	Export Structurizr DSL views to PlantUML diagrams (build/structurizr/diagrams/)
make preview	Open the generated HTML in your default browser
make clean	Remove the build/ directory
make adr-new TITLE="..."	Create a new ADR using the configured MADR template
make adr-list	List existing Architecture Decision Records
make adr-link FROM=2 LINK="Supercedes" TO=1 REV="Superceded by"	Link or supersede ADRs

Run make help (or simply make) anytime to see the full list of commands.

---

Direct CLI Commands

If you prefer using the underlying CLI tools directly without make:

1. Build Documentation via docToolchain (dtcw)

# Build complete documentation suite (HTML + PDF)
DTC_CONFIG_FILE=tools/doctoolchain/docToolchainConfig.groovy ./tools/doctoolchain/dtcw docker buildDocs

# Or build individual formats:
DTC_CONFIG_FILE=tools/doctoolchain/docToolchainConfig.groovy ./tools/doctoolchain/dtcw docker exportStructurizr exportMarkdown collectIncludes generateHTML
DTC_CONFIG_FILE=tools/doctoolchain/docToolchainConfig.groovy ./tools/doctoolchain/dtcw docker exportStructurizr exportMarkdown collectIncludes generatePDF

Build outputs are placed in the build/ directory:

• HTML: build/html5/arc42/arc42.html
• PDF: build/pdf/arc42/arc42.pdf

The build process automatically runs in order:

1. Converts Markdown ADRs (docs/adr/*.md) into AsciiDoc (build/adr/*.adoc), prefixing with ADR- for docToolchain compatibility.
2. Generates the include index build/_includes/ADR_includes.adoc (gracefully skipped if no ADRs are created yet).
3. Exports Structurizr DSL views to PlantUML diagrams (build/structurizr/diagrams/*.puml).
4. Embeds diagrams and ADRs directly into the arc42 chapters (Chapters 3, 5, 6, 7, and 9).

2. Live Preview

xdg-open build/html5/arc42/arc42.html 2>/dev/null || open build/html5/arc42/arc42.html

---

Working with Architecture Decision Records (ADRs)

ADRs are managed using adr-tools via Docker Compose with targeted volume mounts (docs/adr and tools/adr/template.md). All records live in docs/adr/.

Create a New ADR

Via make:

make adr-new TITLE="Choose Message Broker"

Or via docker compose:

LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)" docker compose -f tools/adr/compose.yaml run --rm adr new "Choose Message Broker"

This creates a numbered file such as docs/adr/0001-choose-message-broker.md based on tools/adr/template.md.

Note: adr-tools new sets the status to Accepted by default. If the decision is still under review, change the status line to Proposed.

List ADRs

make adr-list
# or: docker compose -f tools/adr/compose.yaml run --rm adr list

Link Decisions (e.g. Supersede)

make adr-link FROM=2 LINK="Supercedes" TO=1 REV="Superceded by"
# or: docker compose -f tools/adr/compose.yaml run --rm adr link 2 Supercedes 1 "Superceded by"

---

Working with Structurizr (C4 Model)

The architecture model and diagrams are defined in docs/structurizr/workspace.dsl.

Perspectives & Views Mapping

Structurizr View	Perspective / C4 Level	Diagram Output	Embedded In arc42
SystemContext-001	System Context (Level 1)	SystemContext-001.puml	Chapter 3: Context and Scope (03_context_and_scope.adoc)
Container-001	Container View (Level 2)	Container-001.puml	Chapter 5: Building Block View (05_building_block_view.adoc)
Component-001	Component View (Level 3)	Component-001.puml	Chapter 5: Building Block View (05_building_block_view.adoc)
Dynamic-001	Dynamic / Runtime Scenario	Dynamic-001.puml	Chapter 6: Runtime View (06_runtime_view.adoc)
Deployment-001	Deployment Architecture	Deployment-001.puml	Chapter 7: Deployment View (07_deployment_view.adoc)

Diagrams are exported during documentation builds (make build, make html, make pdf), or manually via:

make diagrams

Exported diagrams reside in build/structurizr/diagrams/ and are not committed to source control.