docs(docs): Update architecture docs with icons and add first real AD…

…Rs (#95)

docs/mkdocs.yml

@@ -33,6 +33,8 @@ extra:
     Github: github
     Docker: docker
     Kubernetes: kubernetes
+    arc42: arc42
+    ADR: adr
 
 # Icons associated with the tags
 theme:
@@ -51,3 +53,5 @@ theme:
       github: simple/github
       docker: simple/docker
       kubernetes: simple/kubernetes
+      arc42: material/pencil-ruler
+      adr: material/arrow-decision-auto

docs/src/architecture/01_introduction_and_goals.md

@@ -1,3 +1,7 @@
+---
+icon: octicons/goal-24
+---
+
 # Introduction and Goals
 
 <!-- See: https://docs.arc42.org/section-1/ -->

docs/src/architecture/02_architecture_constraints.md

@@ -1,3 +1,7 @@
+---
+icon: material/handcuffs
+---
+
 # Architecture Constraints
 
 <!-- See: https://docs.arc42.org/section-2/ -->

docs/src/architecture/03_system_scope_and_context.md

@@ -1,3 +1,7 @@
+---
+icon: material/telescope
+---
+
 # System Scope and Context
 
 <!-- See: https://docs.arc42.org/section-3/ -->

docs/src/architecture/04_solution_strategy.md

@@ -1,3 +1,7 @@
+---
+icon: material/strategy
+---
+
 # Solution Strategy
 
 <!-- See: https://docs.arc42.org/section-4/ -->

docs/src/architecture/05_building_block_view.md

@@ -1,3 +1,7 @@
+---
+icon: material/toy-brick-search
+---
+
 # Building Block View
 
 <!-- See: https://docs.arc42.org/section-5/ -->

docs/src/architecture/06_runtime_view.md

@@ -1,3 +1,7 @@
+---
+icon: material/run-fast
+---
+
 # Runtime View
 
 <!-- See: https://docs.arc42.org/section-6/ -->

docs/src/architecture/07_deployment_view.md

@@ -1,3 +1,7 @@
+---
+icon: material/server-network
+---
+
 # Deployment View
 
 <!-- See: https://docs.arc42.org/section-7/ -->

docs/src/architecture/08_concepts.md

@@ -1,3 +1,7 @@
+---
+icon: material/thought-bubble
+---
+
 # Cross-cutting Concepts
 
 <!-- See: https://docs.arc42.org/section-8/ -->

docs/src/architecture/09_architecture_decisions/0001-arch-std.md

@@ -0,0 +1,55 @@
+---
+    title: 0001 Architecture Documentation Standard
+    adr:
+        author: Steven Johnson
+        created: 15-Nov-2023
+        status:  accepted
+    tags:
+        - arc42
+---
+
+## Context
+
+There needs to be a commonly understood and well documented structure to Architecture Documentation.
+Architecture Documentation is the responsibility of the entire team.
+A standardized structure to that documentation helps with collaboration.
+
+## Assumptions
+
+* Architecture documentation is the collective responsibility of the development team.
+* A well documented structure to that documentation will aid in collaboration and maintenance of the documentation.
+
+## Decision
+
+We will be using the [arc42] standard for organizing architecture documentation.
+
+## Risks
+
+* That [arc42] becomes unmaintained upstream, or some flaw is found with its methodology.
+* That the team does not understand the structure of the architecture documentation or necessity to maintain it.
+
+## Consequences
+
+If we do:
+
+* It is easier to maintain documentation when there is an agreed structure to it.
+* It is easier to on-board new members of the team when there are resources to help understand the documentation and its structure.
+* Architecture Documentation will be of higher quality and more meaningfully reviewed in the context of an agreed structure.
+
+If we don't:
+
+* Architecture docs will be "ad-hoc".
+* Difficult for the team to meaningfully collaborate on Architecture.
+* Difficult to maintain.
+* Difficult to ensure the necessary information is captured.
+* Difficult to iterate and be agile.
+
+## More Information
+
+* [arc42]
+* [Original Templates](https://github.com/arc42/arc42-template/tree/master/dist)
+* [Main Documentation](https://docs.arc42.org/home/)
+* [Books](https://leanpub.com/b/arc42complete)
+* [Examples](https://arc42.org/examples)
+
+[arc42]: https://arc42.org

docs/src/architecture/09_architecture_decisions/0002-adr.md

@@ -0,0 +1,47 @@
+---
+    title: 0002 Architecture Decision Records
+    adr:
+        author: Steven Johnson <[email protected]>
+        created: 15-Nov-2023
+        status:  accepted
+        extends:
+            - 0001-arch-std
+    tags:
+        - arc42
+        - ADR
+---
+
+## Context
+
+Architecture Decision Records are part of [arc42].
+We need an efficient and automated way to manage them.
+The system needs to be easy for anyone to use as documenting Architecture Decisions is a team responsibility.
+
+## Assumptions
+
+* The team as a whole is responsible for creating and maintaining Architecture Decision Records.
+
+## Decision
+
+We will use the [MkDocs Material ADR Plugin] to assist in ADR documentation and automation.
+
+## Risks
+
+* The plugin doesn't get maintained or has technical issues
+
+This risk can be mitigated because the plugin is simple, and it would be easy for us to fork and maintain it as required.
+
+## Consequences
+
+* ADR become easier for people to author.
+* This should assist in making the team more pro-active in their creation and maintenance.
+
+## More Information
+
+* [arc42]
+* [arc42 ADR Guide](https://docs.arc42.org/section-9/)
+* [MkDocs Material ADR Plugin]
+* [Fixed fork of MkDocs Material ADR Plugin](https://github.com/stevenj/mkdocs-material-adr)
+
+[arc42]: https://arc42.org
+[MkDocs Material ADR Plugin]: https://github.com/Kl0ven/mkdocs-material-adr/tree/main

docs/src/architecture/09_architecture_decisions/index.md

@@ -1,7 +1,5 @@
 ---
-
-tags:
-    - tag1
+icon: material/arrow-decision-auto
 ---
 
 # Architecture Decisions

docs/src/architecture/09_architecture_decisions/template/.pages

@@ -0,0 +1 @@
+hide: true

docs/src/architecture/09_architecture_decisions/template/0xxx-template.md_

@@ -0,0 +1,42 @@
+---
+    title: 0xxx all
+    adr:
+        author: Steven Johnson
+        created: 15-Nov-2023
+        status:  draft / proposed / accepted / rejected / superseded
+        superseded_by: 0007-accepted
+        extends:
+            - 0001-draft
+            - 0002-proposed
+            - 0003-accepted
+    tags:
+        - tag2
+        - tag3
+---
+
+--- *This is a template ADR to be copied and completed when adding new ADR* ---
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Assumptions
+
+Anything that could cause problems if untrue now or later
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Risks
+
+Anything that could cause malfunction, delay, or other negative impacts
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+## More Information
+
+Provide additional evidence/confidence for the decision outcome
+Links to other decisions and resources might here appear as well.

docs/src/architecture/10_quality_requirements.md

@@ -1,3 +1,7 @@
+---
+icon: material/quality-high
+---
+
 # Quality Requirements
 
 <!-- See: https://docs.arc42.org/section-10/ -->

docs/src/architecture/11_technical_risks.md

@@ -1,3 +1,7 @@
+---
+icon: fontawesome/solid/biohazard
+---
+
 # Risks and Technical Debts
 
 <!-- See: https://docs.arc42.org/section-11/ -->

docs/src/architecture/12_glossary.md

@@ -1,3 +1,7 @@
+---
+icon: material/format-list-group-plus
+---
+
 # Glossary
 
 <!-- See: https://docs.arc42.org/section-12/ -->

docs/src/architecture/index.md

@@ -1,5 +1,7 @@
 ---
 icon: material/pencil-ruler
+tags: 
+    - arc42
 ---
 
 <!-- cspell: words Hruschka Gernot Starke -->