Software Architecture Documentation Template using Arc42, C4 Model, M…

…ermaid, Mkdocs Material, GitHub Page

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: Software Architecture CI
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -0,0 +1 @@
+site

README.md

@@ -0,0 +1,31 @@
+# Software Architecture Documentation Template
+
+The sample this documentation is based on can be downloaded at [arc42.org](https://github.com/arc42/arc42-template/raw/master/dist/arc42-template-EN-withhelp-html.zip).
+
+## Capabilities
+
+* `Arc42` - the documentation template in place, [link](https://arc42.org/).
+* `Mermaid` - used for diagramming to better illustrate your software architecture, [link](https://mermaid.js.org/).
+* `C4 Model` - For context and container representation of your systems, [link](https://c4model.com/).
+* `Mkdocs  Material` - is being used as the static site generator along with the material template, [link](https://squidfunk.github.io/mkdocs-material/).
+* `GitHub Action` - CI/CD in place to deploy the documentation as a GitHub Page site.
+
+## Commands
+
+* `pip install -r requirements.txt` - install the dependencies.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        diagrams  # Folder containing your Mermaid and C4 diagrams.
+        decisions # The location of your architecture decisions records.
+        images    # Images displayed in the pages.
+        css/js    # To be used only if you need to customize the site.
+        .github   # GitHub Action CI/CD pipeline.
+        ...       # Other markdown pages, images and other files.

docs/architecture-constraints.md

@@ -0,0 +1,19 @@
+---
+title: Architecture Constraints
+---
+
+# Architecture Constraints
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## XXXXXXXXXXX
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## YYYYYYYYYYY
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## ZZZZZZZZZZZZ
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.

docs/building-block-view.md

@@ -0,0 +1,19 @@
+---
+title: Building Block View
+---
+
+# Building Block View
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Containers
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Components
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Codes
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.

docs/context-scope.md

@@ -0,0 +1,15 @@
+---
+title: Context and Scope
+---
+
+# Context and Scope
+
+## Business Context
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+{% include 'diagrams/c4-context.md' %}
+
+## Technical Context
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.

docs/cross-cutting-concepts.md

@@ -0,0 +1,19 @@
+---
+title: Cross-cutting Concepts
+---
+
+# Cross-cutting Concepts
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Concept 1
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Concept 2
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Concept 3
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.

docs/css/custom.css

@@ -0,0 +1,12 @@
+.new-custom-class {
+    color: red;
+}
+
+/* delete this block to enable 'table of contents' for pages */
+.md-sidebar--secondary {
+    display: none !important;
+}
+
+.md-grid {
+    max-width: 90% !important;
+}

docs/decisions/0000-index.md

@@ -0,0 +1,23 @@
+---
+    title: Architecture Decision Records
+    date: 2024-11-27
+---
+
+# Architecture Decision Records
+
+!!! Note
+
+    This section contains the **Architecture Decision Records** for the project.
+
+## Decision Statuses
+
+- draft
+- proposed
+- accepted
+- rejected
+- superseded
+- test
+
+## Decisions
+
+{{ adr_summary(adr_path="docs/decisions", adr_style="MADR3") }}

docs/decisions/0001-sample.md

@@ -0,0 +1,35 @@
+---
+    title: Sample Decision
+    adr:
+        author: Orleando Dassi
+        created: 27-Nov-2024
+        status:  draft
+    status: draft
+    date: 2024-11-27
+    deciders: Orleando Dassi
+---
+
+# Sample Decision
+
+## 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/deployment-view.md

@@ -0,0 +1,19 @@
+---
+title: Deployment View
+---
+
+# Deployment View
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Infrastructure Level 1
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Infrastructure Level 2
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.
+
+## Infrastructure Level 3
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx.

docs/diagrams/c4-component.md

@@ -0,0 +1,38 @@
+``` mermaid
+C4Component
+title Component diagram for Internet Banking System - API Application
+
+Container(spa, "Single Page Application", "javascript and angular", "Provides all the internet banking functionality to customers via their web browser.")
+Container(ma, "Mobile App", "Xamarin", "Provides a limited subset to the internet banking functionality to customers via their mobile mobile device.")
+ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
+System_Ext(mbs, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
+
+Container_Boundary(api, "API Application") {
+    Component(sign, "Sign In Controller", "MVC Rest Controller", "Allows users to sign in to the internet banking system")
+    Component(accounts, "Accounts Summary Controller", "MVC Rest Controller", "Provides customers with a summary of their bank accounts")
+    Component(security, "Security Component", "Spring Bean", "Provides functionality related to singing in, changing passwords, etc.")
+    Component(mbsfacade, "Mainframe Banking System Facade", "Spring Bean", "A facade onto the mainframe banking system.")
+
+    Rel(sign, security, "Uses")
+    Rel(accounts, mbsfacade, "Uses")
+    Rel(security, db, "Read & write to", "JDBC")
+    Rel(mbsfacade, mbs, "Uses", "XML/HTTPS")
+}
+
+Rel_Back(spa, sign, "Uses", "JSON/HTTPS")
+Rel(spa, accounts, "Uses", "JSON/HTTPS")
+
+Rel(ma, sign, "Uses", "JSON/HTTPS")
+Rel(ma, accounts, "Uses", "JSON/HTTPS")
+
+UpdateRelStyle(spa, sign, $offsetY="-40")
+UpdateRelStyle(spa, accounts, $offsetX="40", $offsetY="40")
+
+UpdateRelStyle(ma, sign, $offsetX="-90", $offsetY="40")
+UpdateRelStyle(ma, accounts, $offsetY="-40")
+
+    UpdateRelStyle(sign, security, $offsetX="-160", $offsetY="10")
+    UpdateRelStyle(accounts, mbsfacade, $offsetX="140", $offsetY="10")
+    UpdateRelStyle(security, db, $offsetY="-40")
+    UpdateRelStyle(mbsfacade, mbs, $offsetY="-40")
+```

docs/diagrams/c4-container.md

@@ -0,0 +1,38 @@
+``` mermaid
+C4Container
+title Container diagram for Internet Banking System
+
+System_Ext(email_system, "E-Mail System", "The internal Microsoft Exchange system", $tags="v1.0")
+Person(customer, Customer, "A customer of the bank, with personal bank accounts", $tags="v1.0")
+
+Container_Boundary(c1, "Internet Banking") {
+    Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all the Internet banking functionality to customers via their web browser")
+    Container_Ext(mobile_app, "Mobile App", "C#, Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device")
+    Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the static content and the Internet banking SPA")
+    ContainerDb(database, "Database", "SQL Database", "Stores user registration information, hashed auth credentials, access logs, etc.")
+    ContainerDb_Ext(backend_api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via API")
+
+}
+
+System_Ext(banking_system, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
+
+Rel(customer, web_app, "Uses", "HTTPS")
+UpdateRelStyle(customer, web_app, $offsetY="60", $offsetX="90")
+Rel(customer, spa, "Uses", "HTTPS")
+UpdateRelStyle(customer, spa, $offsetY="-40")
+Rel(customer, mobile_app, "Uses")
+UpdateRelStyle(customer, mobile_app, $offsetY="-30")
+
+Rel(web_app, spa, "Delivers")
+UpdateRelStyle(web_app, spa, $offsetX="130")
+Rel(spa, backend_api, "Uses", "async, JSON/HTTPS")
+Rel(mobile_app, backend_api, "Uses", "async, JSON/HTTPS")
+Rel_Back(database, backend_api, "Reads from and writes to", "sync, JDBC")
+
+Rel(email_system, customer, "Sends e-mails to")
+UpdateRelStyle(email_system, customer, $offsetX="-45")
+Rel(backend_api, email_system, "Sends e-mails using", "sync, SMTP")
+UpdateRelStyle(backend_api, email_system, $offsetY="-60")
+Rel(backend_api, banking_system, "Uses", "sync/async, XML/HTTPS")
+UpdateRelStyle(backend_api, banking_system, $offsetY="-50", $offsetX="-140")
+```

docs/diagrams/c4-context.md

@@ -0,0 +1,44 @@
+``` mermaid
+C4Context
+title System Context diagram for Internet Banking System
+Enterprise_Boundary(b0, "BankBoundary0") {
+Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
+Person(customerB, "Banking Customer B")
+Person_Ext(customerC, "Banking Customer C", "desc")
+
+Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
+
+System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
+
+Enterprise_Boundary(b1, "BankBoundary") {
+
+    SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
+
+    System_Boundary(b2, "BankBoundary2") {
+    System(SystemA, "Banking System A")
+    System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
+    }
+
+    System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
+    SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
+
+    Boundary(b3, "BankBoundary3", "boundary") {
+    SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
+    SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
+    }
+}
+}
+
+BiRel(customerA, SystemAA, "Uses")
+BiRel(SystemAA, SystemE, "Uses")
+Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
+Rel(SystemC, customerA, "Sends e-mails to")
+
+UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
+UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
+UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
+UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
+UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
+
+UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```