Initial version

.github/workflows/deploy-docs.yml

@@ -0,0 +1,38 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main  # Trigger the workflow on push to the main branch
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+
+      - name: Cache Docker layers
+        uses: actions/cache@v2
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+
+      - name: Generate PlantUML diagrams
+        run: docker-compose run --rm generate-diagrams
+
+      - name: Generate HTML documentation
+        run: docker-compose run --rm generate-docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/docs
+

README.md

@@ -0,0 +1,60 @@
+# Software Architecture Documentation with arc42 and C4 Model 
+
+This repository provides an example of generating architecture documentation using the arc42 template and the C4 model, with the help of Structurizr CLI and Asciidoctor. The documentation includes various architectural views and diagrams, generated automatically using Docker and Docker Compose.
+
+## Overview
+
+The repository demonstrates how to:
+1. Define architecture using Structurizr DSL.
+2. Generate PlantUML diagrams using Structurizr CLI.
+3. Generate HTML documentation using Asciidoctor.
+4. Serve the documentation using Nginx or GitHub Pages.
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+
+## Usage
+
+Follow these steps to generate and serve the architecture documentation.
+
+### 1. Generate PlantUML diagrams
+
+Run the following command to generate PlantUML diagrams from the Structurizr DSL:
+
+```sh
+docker-compose run --rm generate-diagrams
+```
+### 2. Generate HTML documentation
+Run the following command to generate the HTML documentation:
+
+````sh
+docker-compose run --rm generate-docs
+````
+### 3. Serve the documentation
+Run the following command to serve the documentation using Nginx:
+
+````sh
+docker-compose up serve-docs
+````
+
+### 4. View the documentation
+Open your browser and go to http://localhost:8080 to view the generated documentation.
+
+## GitHub Pages Demo
+You can view the demo of this documentation on GitHub Pages at the following [URL](https://<your-github-username>.github.io/<your-repository-name>/).
+
+## Explanation of Key Files
+- src/docs/structurizr/structurizr.dsl: Defines the architecture using Structurizr DSL.
+- src/docs/asciidoc/index.adoc: Main AsciiDoc file that includes other sections.
+- src/docs/asciidoc/sections/: Directory containing individual AsciiDoc section files.
+- docker-compose.yml: Docker Compose configuration to orchestrate the generation and serving of documentation.
+
+## Customization
+You can customize the Structurizr DSL file (structurizr.dsl) to reflect your own system's architecture. Similarly, you can edit the AsciiDoc files in the sections directory to include more detailed information about your system.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

build/docs/.asciidoctor/diagram/structurizr-Component-001.png.cache

@@ -0,0 +1 @@
+{"checksum":"plantuml-md5-be4964e4a52214fa7c6a3f1c7982c5ff","options":{"size_limit":"4096"},"width":344,"height":345}

build/docs/.asciidoctor/diagram/structurizr-Container-001.png.cache

@@ -0,0 +1 @@
+{"checksum":"plantuml-md5-472c1c2cff83c3fd62b54c68a4637fa9","options":{"size_limit":"4096"},"width":726,"height":202}

build/docs/.asciidoctor/diagram/structurizr-Deployment-001.png.cache

@@ -0,0 +1 @@
+{"checksum":"plantuml-md5-1222f37eb53c06b1a65b3c7ac23fabc7","options":{"size_limit":"4096"},"width":517,"height":193}

build/docs/.asciidoctor/diagram/structurizr-SystemContext-001.png.cache

@@ -0,0 +1 @@
+{"checksum":"plantuml-md5-ad6f96440bf1d5d50a427c16ed0d32a2","options":{"size_limit":"4096"},"width":378,"height":180}

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  generate-diagrams:
+    image: structurizr/cli:latest
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+    command: ["export", "-workspace", "src/docs/structurizr/structurizr.dsl", "-format", "plantuml"]
+
+  generate-docs:
+    image: asciidoctor/docker-asciidoctor:latest
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+    environment:
+      - PLANTUML_LIMIT_SIZE=8192
+    command: ["asciidoctor", "-r", "asciidoctor-diagram", "-D", "build/docs", "src/docs/asciidoc/index.adoc"]
+
+  serve-docs:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - ./build/docs:/usr/share/nginx/html

src/docs/asciidoc/index.adoc

@@ -0,0 +1,17 @@
+= Software Architecture Documentation Template
+Version 1.0, June 2024.
+:toc:
+:toc-placement: preamble
+
+include::sections/01_introduction_and_goals.adoc[]
+include::sections/02_constraints.adoc[]
+include::sections/03_context_and_scope.adoc[]
+include::sections/04_solution_strategy.adoc[]
+include::sections/05_building_block_view.adoc[]
+include::sections/06_runtime_view.adoc[]
+include::sections/07_deployment_view.adoc[]
+include::sections/08_crosscutting_concepts.adoc[]
+include::sections/09_decision_log.adoc[]
+include::sections/10_quality_scenarios.adoc[]
+include::sections/11_risks_and_technical_debt.adoc[]
+include::sections/12_glossary.adoc[]

src/docs/asciidoc/sections/01_introduction_and_goals.adoc

@@ -0,0 +1,2 @@
+== 1. Introduction and Goals
+This section provides an overview of the system's goals and stakeholders.

src/docs/asciidoc/sections/02_constraints.adoc

@@ -0,0 +1,3 @@
+
+== 2. Architecture Constraints
+List of technical, organizational, and other constraints.

src/docs/asciidoc/sections/03_context_and_scope.adoc

@@ -0,0 +1,9 @@
+
+== 3. System Context and Scope
+
+=== 3.1. System Context
+
+[plantuml, structurizr-SystemContext-001, png]
+....
+include::../../structurizr/structurizr-SystemContext-001.puml[]
+....

src/docs/asciidoc/sections/04_solution_strategy.adoc

@@ -0,0 +1,10 @@
+
+== 4. Solution Strategy
+
+=== 4.1. Technology
+
+Which techonologies are used in the solution?
+
+=== 4.2. Methods for high-level design
+
+Which methods are used for high-level design?

src/docs/asciidoc/sections/05_building_block_view.adoc

@@ -0,0 +1,17 @@
+
+== 5. Building Block View
+
+=== 5.1: System Context
+
+[plantuml, structurizr-Container-001, png]
+....
+include::../../structurizr/structurizr-Container-001.puml[]
+....
+
+=== 5.2: Container
+
+[plantuml, structurizr-Component-001, png]
+....
+include::../../structurizr/structurizr-Component-001.puml[]
+....
+

src/docs/asciidoc/sections/06_runtime_view.adoc

@@ -0,0 +1,6 @@
+
+== 6. Runtime View
+
+It shows the behavior of one of several building blocks in the form of essential use cases.
+
+=== 6.1. Login use case

src/docs/asciidoc/sections/07_deployment_view.adoc

@@ -0,0 +1,11 @@
+
+== 7. Deployment View
+
+This section describes how the software system is deployed, including the hardware, software, and networking components.
+
+=== 7.1. Deployment Diagram
+
+[plantuml, structurizr-Deployment-001, png]
+....
+include::../../structurizr/structurizr-Deployment-001.puml[]
+....

src/docs/asciidoc/sections/08_crosscutting_concepts.adoc

@@ -0,0 +1,12 @@
+
+== 8. Cross-cutting Concepts
+
+Description of cross-cutting concerns such as security, performance, and logging.
+
+=== 8.1. Security
+
+==== 8.1.1. Authentication 
+
+=== 8.2. Performance
+
+=== 8.3. Logging

src/docs/asciidoc/sections/09_decision_log.adoc

@@ -0,0 +1,4 @@
+
+== 9. Architecture Decisions Records
+
+include::adrs/0001-login-decision.adoc[]

src/docs/asciidoc/sections/10_quality_scenarios.adoc

@@ -0,0 +1,30 @@
+
+== 10. Quality Scenarios
+
+=== 10.1. Performance
+
+TODO: Describe performance-related quality scenarios.
+
+=== 10.2. Scalability
+
+TODO: Describe scalability-related quality scenarios.
+
+=== 10.3. Reliability
+
+TODO: Describe reliability-related quality scenarios.
+
+=== 10.4. Availability
+
+TODO: Describe availability-related quality scenarios.
+
+=== 10.5. Security
+
+TODO: Describe security-related quality scenarios.
+
+=== 10.6. Maintainability
+
+TODO: Describe maintainability-related quality scenarios.
+
+=== 10.7. Portability
+
+TODO: Describe portability-related quality scenarios.

src/docs/asciidoc/sections/11_risks_and_technical_debt.adoc

@@ -0,0 +1,10 @@
+
+== 11. Risks and Technical Debt
+
+=== 11.1. Risks
+
+Identify and describe potential risks.
+
+=== 11.2. Technical Debt
+
+Identify and describe technical debt in the system.

src/docs/asciidoc/sections/12_glossary.adoc

@@ -0,0 +1,21 @@
+
+== 12. Glossary
+
+|===
+| Term | Definition
+
+| Term 1
+| Definition of term 1
+
+| Term 2
+| Definition of term 2
+
+| Term 3
+| Definition of term 3
+
+| Term 4
+| Definition of term 4
+
+| Term 5
+| Definition of term 5
+|===

src/docs/asciidoc/sections/adrs/0001-login-decision.adoc

@@ -0,0 +1,15 @@
+
+=== 9.1. Login decision
+
+==== 9.1.1. Context and Problem Statement
+
+We want to enable user login.
+
+==== 9.1.2. Considered Options
+
+* Option 1
+* Option 2
+
+==== 9.1.3. Decision Outcome
+
+We selected option 1, because X.

src/docs/structurizr/structurizr-Component-001-key.puml

@@ -0,0 +1,28 @@
+@startuml
+set separator none
+
+skinparam {
+  shadowing false
+  arrowFontSize 15
+  defaultTextAlignment center
+  wrapWidth 100
+  maxMessageSize 100
+}
+hide stereotype
+
+skinparam rectangle<<_transparent>> {
+  BorderColor transparent
+  BackgroundColor transparent
+  FontColor transparent
+}
+
+skinparam rectangle<<1>> {
+  BackgroundColor #85bbf0
+  FontColor #000000
+  BorderColor #5d82a8
+  roundCorner 20
+}
+rectangle "==Component" <<1>>
+
+
+@enduml

src/docs/structurizr/structurizr-Component-001.puml

@@ -0,0 +1,41 @@
+@startuml
+set separator none
+title System - Web Application - Components
+
+left to right direction
+
+skinparam {
+  arrowFontSize 10
+  defaultTextAlignment center
+  wrapWidth 200
+  maxMessageSize 100
+}
+
+hide stereotype
+
+skinparam rectangle<<System.WebApplication.ComponentA>> {
+  BackgroundColor #85bbf0
+  FontColor #000000
+  BorderColor #5d82a8
+  roundCorner 20
+  shadowing false
+}
+skinparam rectangle<<System.WebApplication.ComponentB>> {
+  BackgroundColor #85bbf0
+  FontColor #000000
+  BorderColor #5d82a8
+  roundCorner 20
+  shadowing false
+}
+skinparam rectangle<<System.WebApplication>> {
+  BorderColor #2e6295
+  FontColor #2e6295
+  shadowing false
+}
+
+rectangle "Web Application\n<size:10>[Container: Java and Spring MVC]</size>" <<System.WebApplication>> {
+  rectangle "==Component A\n<size:10>[Component: Spring Bean]</size>\n\nA component within the web application." <<System.WebApplication.ComponentA>> as System.WebApplication.ComponentA
+  rectangle "==Component B\n<size:10>[Component: Spring Bean]</size>\n\nAnother component within the web application." <<System.WebApplication.ComponentB>> as System.WebApplication.ComponentB
+}
+
+@enduml