Skip to content

Commit 94ff2db

Browse files
milanmmilanm
committed
Initial version
1 parent a5b8639 commit 94ff2db

36 files changed

+1420
-0
lines changed

‎.github/workflows/deploy-docs.yml

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main # Trigger the workflow on push to the main branch
7+
8+
jobs:
9+
build-and-deploy:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout Repository
14+
uses: actions/checkout@v2
15+
16+
- name: Set up Docker Buildx
17+
uses: docker/setup-buildx-action@v1
18+
19+
- name: Cache Docker layers
20+
uses: actions/cache@v2
21+
with:
22+
path: /tmp/.buildx-cache
23+
key: ${{ runner.os }}-buildx-${{ github.sha }}
24+
restore-keys: |
25+
${{ runner.os }}-buildx-
26+
27+
- name: Generate PlantUML diagrams
28+
run: docker-compose run --rm generate-diagrams
29+
30+
- name: Generate HTML documentation
31+
run: docker-compose run --rm generate-docs
32+
33+
- name: Deploy to GitHub Pages
34+
uses: peaceiris/actions-gh-pages@v3
35+
with:
36+
github_token: ${{ secrets.GITHUB_TOKEN }}
37+
publish_dir: ./build/docs
38+

‎README.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Software Architecture Documentation with arc42 and C4 Model
2+
3+
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.
4+
5+
## Overview
6+
7+
The repository demonstrates how to:
8+
1. Define architecture using Structurizr DSL.
9+
2. Generate PlantUML diagrams using Structurizr CLI.
10+
3. Generate HTML documentation using Asciidoctor.
11+
4. Serve the documentation using Nginx or GitHub Pages.
12+
13+
## Prerequisites
14+
15+
- Docker
16+
- Docker Compose
17+
18+
## Usage
19+
20+
Follow these steps to generate and serve the architecture documentation.
21+
22+
### 1. Generate PlantUML diagrams
23+
24+
Run the following command to generate PlantUML diagrams from the Structurizr DSL:
25+
26+
```sh
27+
docker-compose run --rm generate-diagrams
28+
```
29+
### 2. Generate HTML documentation
30+
Run the following command to generate the HTML documentation:
31+
32+
````sh
33+
docker-compose run --rm generate-docs
34+
````
35+
### 3. Serve the documentation
36+
Run the following command to serve the documentation using Nginx:
37+
38+
````sh
39+
docker-compose up serve-docs
40+
````
41+
42+
### 4. View the documentation
43+
Open your browser and go to http://localhost:8080 to view the generated documentation.
44+
45+
## GitHub Pages Demo
46+
You can view the demo of this documentation on GitHub Pages at the following [URL](https://<your-github-username>.github.io/<your-repository-name>/).
47+
48+
## Explanation of Key Files
49+
- src/docs/structurizr/structurizr.dsl: Defines the architecture using Structurizr DSL.
50+
- src/docs/asciidoc/index.adoc: Main AsciiDoc file that includes other sections.
51+
- src/docs/asciidoc/sections/: Directory containing individual AsciiDoc section files.
52+
- docker-compose.yml: Docker Compose configuration to orchestrate the generation and serving of documentation.
53+
54+
## Customization
55+
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.
56+
57+
## License
58+
59+
This project is licensed under the MIT License - see the LICENSE file for details.
60+

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

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

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

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

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

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

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

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

‎build/docs/index.html

+707
Large diffs are not rendered by default.

‎build/docs/structurizr-Component-001.png

16 KB
Loading

‎build/docs/structurizr-Container-001.png

17.3 KB
Loading

‎build/docs/structurizr-Deployment-001.png

14.4 KB
Loading

‎build/docs/structurizr-SystemContext-001.png

10.4 KB
Loading

‎docker-compose.yml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
services:
2+
generate-diagrams:
3+
image: structurizr/cli:latest
4+
volumes:
5+
- .:/workspace
6+
working_dir: /workspace
7+
command: ["export", "-workspace", "src/docs/structurizr/structurizr.dsl", "-format", "plantuml"]
8+
9+
generate-docs:
10+
image: asciidoctor/docker-asciidoctor:latest
11+
volumes:
12+
- .:/workspace
13+
working_dir: /workspace
14+
environment:
15+
- PLANTUML_LIMIT_SIZE=8192
16+
command: ["asciidoctor", "-r", "asciidoctor-diagram", "-D", "build/docs", "src/docs/asciidoc/index.adoc"]
17+
18+
serve-docs:
19+
image: nginx:alpine
20+
ports:
21+
- "8080:80"
22+
volumes:
23+
- ./build/docs:/usr/share/nginx/html

‎src/docs/asciidoc/index.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
= Software Architecture Documentation Template
2+
Version 1.0, June 2024.
3+
:toc:
4+
:toc-placement: preamble
5+
6+
include::sections/01_introduction_and_goals.adoc[]
7+
include::sections/02_constraints.adoc[]
8+
include::sections/03_context_and_scope.adoc[]
9+
include::sections/04_solution_strategy.adoc[]
10+
include::sections/05_building_block_view.adoc[]
11+
include::sections/06_runtime_view.adoc[]
12+
include::sections/07_deployment_view.adoc[]
13+
include::sections/08_crosscutting_concepts.adoc[]
14+
include::sections/09_decision_log.adoc[]
15+
include::sections/10_quality_scenarios.adoc[]
16+
include::sections/11_risks_and_technical_debt.adoc[]
17+
include::sections/12_glossary.adoc[]

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

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

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

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
== 2. Architecture Constraints
3+
List of technical, organizational, and other constraints.

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

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
2+
== 3. System Context and Scope
3+
4+
=== 3.1. System Context
5+
6+
[plantuml, structurizr-SystemContext-001, png]
7+
....
8+
include::../../structurizr/structurizr-SystemContext-001.puml[]
9+
....

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
== 4. Solution Strategy
3+
4+
=== 4.1. Technology
5+
6+
Which techonologies are used in the solution?
7+
8+
=== 4.2. Methods for high-level design
9+
10+
Which methods are used for high-level design?

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

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
2+
== 5. Building Block View
3+
4+
=== 5.1: System Context
5+
6+
[plantuml, structurizr-Container-001, png]
7+
....
8+
include::../../structurizr/structurizr-Container-001.puml[]
9+
....
10+
11+
=== 5.2: Container
12+
13+
[plantuml, structurizr-Component-001, png]
14+
....
15+
include::../../structurizr/structurizr-Component-001.puml[]
16+
....
17+

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
== 6. Runtime View
3+
4+
It shows the behavior of one of several building blocks in the form of essential use cases.
5+
6+
=== 6.1. Login use case

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

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
== 7. Deployment View
3+
4+
This section describes how the software system is deployed, including the hardware, software, and networking components.
5+
6+
=== 7.1. Deployment Diagram
7+
8+
[plantuml, structurizr-Deployment-001, png]
9+
....
10+
include::../../structurizr/structurizr-Deployment-001.puml[]
11+
....

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

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
== 8. Cross-cutting Concepts
3+
4+
Description of cross-cutting concerns such as security, performance, and logging.
5+
6+
=== 8.1. Security
7+
8+
==== 8.1.1. Authentication
9+
10+
=== 8.2. Performance
11+
12+
=== 8.3. Logging

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

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
== 9. Architecture Decisions Records
3+
4+
include::adrs/0001-login-decision.adoc[]

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

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
2+
== 10. Quality Scenarios
3+
4+
=== 10.1. Performance
5+
6+
TODO: Describe performance-related quality scenarios.
7+
8+
=== 10.2. Scalability
9+
10+
TODO: Describe scalability-related quality scenarios.
11+
12+
=== 10.3. Reliability
13+
14+
TODO: Describe reliability-related quality scenarios.
15+
16+
=== 10.4. Availability
17+
18+
TODO: Describe availability-related quality scenarios.
19+
20+
=== 10.5. Security
21+
22+
TODO: Describe security-related quality scenarios.
23+
24+
=== 10.6. Maintainability
25+
26+
TODO: Describe maintainability-related quality scenarios.
27+
28+
=== 10.7. Portability
29+
30+
TODO: Describe portability-related quality scenarios.

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
== 11. Risks and Technical Debt
3+
4+
=== 11.1. Risks
5+
6+
Identify and describe potential risks.
7+
8+
=== 11.2. Technical Debt
9+
10+
Identify and describe technical debt in the system.

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

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
== 12. Glossary
3+
4+
|===
5+
| Term | Definition
6+
7+
| Term 1
8+
| Definition of term 1
9+
10+
| Term 2
11+
| Definition of term 2
12+
13+
| Term 3
14+
| Definition of term 3
15+
16+
| Term 4
17+
| Definition of term 4
18+
19+
| Term 5
20+
| Definition of term 5
21+
|===

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

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
=== 9.1. Login decision
3+
4+
==== 9.1.1. Context and Problem Statement
5+
6+
We want to enable user login.
7+
8+
==== 9.1.2. Considered Options
9+
10+
* Option 1
11+
* Option 2
12+
13+
==== 9.1.3. Decision Outcome
14+
15+
We selected option 1, because X.

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

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
@startuml
2+
set separator none
3+
4+
skinparam {
5+
shadowing false
6+
arrowFontSize 15
7+
defaultTextAlignment center
8+
wrapWidth 100
9+
maxMessageSize 100
10+
}
11+
hide stereotype
12+
13+
skinparam rectangle<<_transparent>> {
14+
BorderColor transparent
15+
BackgroundColor transparent
16+
FontColor transparent
17+
}
18+
19+
skinparam rectangle<<1>> {
20+
BackgroundColor #85bbf0
21+
FontColor #000000
22+
BorderColor #5d82a8
23+
roundCorner 20
24+
}
25+
rectangle "==Component" <<1>>
26+
27+
28+
@enduml

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

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
@startuml
2+
set separator none
3+
title System - Web Application - Components
4+
5+
left to right direction
6+
7+
skinparam {
8+
arrowFontSize 10
9+
defaultTextAlignment center
10+
wrapWidth 200
11+
maxMessageSize 100
12+
}
13+
14+
hide stereotype
15+
16+
skinparam rectangle<<System.WebApplication.ComponentA>> {
17+
BackgroundColor #85bbf0
18+
FontColor #000000
19+
BorderColor #5d82a8
20+
roundCorner 20
21+
shadowing false
22+
}
23+
skinparam rectangle<<System.WebApplication.ComponentB>> {
24+
BackgroundColor #85bbf0
25+
FontColor #000000
26+
BorderColor #5d82a8
27+
roundCorner 20
28+
shadowing false
29+
}
30+
skinparam rectangle<<System.WebApplication>> {
31+
BorderColor #2e6295
32+
FontColor #2e6295
33+
shadowing false
34+
}
35+
36+
rectangle "Web Application\n<size:10>[Container: Java and Spring MVC]</size>" <<System.WebApplication>> {
37+
rectangle "==Component A\n<size:10>[Component: Spring Bean]</size>\n\nA component within the web application." <<System.WebApplication.ComponentA>> as System.WebApplication.ComponentA
38+
rectangle "==Component B\n<size:10>[Component: Spring Bean]</size>\n\nAnother component within the web application." <<System.WebApplication.ComponentB>> as System.WebApplication.ComponentB
39+
}
40+
41+
@enduml

0 commit comments

Comments
 (0)