From 246d0140e1942062939d995b144deb236c6e7e1f Mon Sep 17 00:00:00 2001
From: Dassi Orleando <me@dassiorleando.xyz>
Date: Wed, 11 Dec 2024 08:00:41 -0500
Subject: [PATCH] Software Architecture Documentation Template using Arc42, C4
 Model, Mermaid, Mkdocs Material, GitHub Page

---
 .github/workflows/ci.yml         | 29 ++++++++++++
 .gitignore                       |  1 +
 README.md                        | 31 +++++++++++++
 docs/architecture-constraints.md | 19 ++++++++
 docs/building-block-view.md      | 19 ++++++++
 docs/context-scope.md            | 15 ++++++
 docs/cross-cutting-concepts.md   | 19 ++++++++
 docs/css/custom.css              | 12 +++++
 docs/decisions/0000-index.md     | 23 ++++++++++
 docs/decisions/0001-sample.md    | 35 ++++++++++++++
 docs/deployment-view.md          | 19 ++++++++
 docs/diagrams/c4-component.md    | 38 ++++++++++++++++
 docs/diagrams/c4-container.md    | 38 ++++++++++++++++
 docs/diagrams/c4-context.md      | 44 ++++++++++++++++++
 docs/diagrams/c4-deployment.md   | 50 ++++++++++++++++++++
 docs/diagrams/c4-dynamic.md      | 18 ++++++++
 docs/glossary.md                 |  7 +++
 docs/index.md                    | 31 +++++++++++++
 docs/introduction-and-goals.md   | 19 ++++++++
 docs/js/custom.js                |  0
 docs/quality-requirements.md     | 15 ++++++
 docs/risks-technical-debts.md    | 19 ++++++++
 docs/runtime-view.md             | 19 ++++++++
 docs/solution-strategy.md        | 19 ++++++++
 mkdocs.yml                       | 78 ++++++++++++++++++++++++++++++++
 requirements.txt                 |  7 +++
 26 files changed, 624 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 docs/architecture-constraints.md
 create mode 100644 docs/building-block-view.md
 create mode 100644 docs/context-scope.md
 create mode 100644 docs/cross-cutting-concepts.md
 create mode 100644 docs/css/custom.css
 create mode 100644 docs/decisions/0000-index.md
 create mode 100644 docs/decisions/0001-sample.md
 create mode 100644 docs/deployment-view.md
 create mode 100644 docs/diagrams/c4-component.md
 create mode 100644 docs/diagrams/c4-container.md
 create mode 100644 docs/diagrams/c4-context.md
 create mode 100644 docs/diagrams/c4-deployment.md
 create mode 100644 docs/diagrams/c4-dynamic.md
 create mode 100644 docs/glossary.md
 create mode 100644 docs/index.md
 create mode 100644 docs/introduction-and-goals.md
 create mode 100644 docs/js/custom.js
 create mode 100644 docs/quality-requirements.md
 create mode 100644 docs/risks-technical-debts.md
 create mode 100644 docs/runtime-view.md
 create mode 100644 docs/solution-strategy.md
 create mode 100644 mkdocs.yml
 create mode 100644 requirements.txt

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..1fdc797
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d97e100
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+site
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2d3485a
--- /dev/null
+++ b/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.
diff --git a/docs/architecture-constraints.md b/docs/architecture-constraints.md
new file mode 100644
index 0000000..3620064
--- /dev/null
+++ b/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.
diff --git a/docs/building-block-view.md b/docs/building-block-view.md
new file mode 100644
index 0000000..03d803c
--- /dev/null
+++ b/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.
diff --git a/docs/context-scope.md b/docs/context-scope.md
new file mode 100644
index 0000000..aeb0db9
--- /dev/null
+++ b/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.
diff --git a/docs/cross-cutting-concepts.md b/docs/cross-cutting-concepts.md
new file mode 100644
index 0000000..1af70fb
--- /dev/null
+++ b/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.
diff --git a/docs/css/custom.css b/docs/css/custom.css
new file mode 100644
index 0000000..a0a3f7f
--- /dev/null
+++ b/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;
+}
diff --git a/docs/decisions/0000-index.md b/docs/decisions/0000-index.md
new file mode 100644
index 0000000..6372ff6
--- /dev/null
+++ b/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") }}
diff --git a/docs/decisions/0001-sample.md b/docs/decisions/0001-sample.md
new file mode 100644
index 0000000..be9c148
--- /dev/null
+++ b/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.
diff --git a/docs/deployment-view.md b/docs/deployment-view.md
new file mode 100644
index 0000000..55fd348
--- /dev/null
+++ b/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.
diff --git a/docs/diagrams/c4-component.md b/docs/diagrams/c4-component.md
new file mode 100644
index 0000000..d6330ea
--- /dev/null
+++ b/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")
+```
\ No newline at end of file
diff --git a/docs/diagrams/c4-container.md b/docs/diagrams/c4-container.md
new file mode 100644
index 0000000..5660d10
--- /dev/null
+++ b/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")
+```
\ No newline at end of file
diff --git a/docs/diagrams/c4-context.md b/docs/diagrams/c4-context.md
new file mode 100644
index 0000000..f636cb6
--- /dev/null
+++ b/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")
+```
\ No newline at end of file
diff --git a/docs/diagrams/c4-deployment.md b/docs/diagrams/c4-deployment.md
new file mode 100644
index 0000000..aeabaad
--- /dev/null
+++ b/docs/diagrams/c4-deployment.md
@@ -0,0 +1,50 @@
+``` mermaid
+C4Deployment
+title Deployment Diagram for Internet Banking System - Live
+
+Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){
+    Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.")
+}
+
+Deployment_Node(comp, "Customer's computer", "Microsoft Windows or Apple macOS"){
+    Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox,<br/> Apple Safari or Microsoft Edge"){
+        Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.")
+    }
+}
+
+Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){
+    Deployment_Node(dn, "bigbank-api*** x8", "Ubuntu 16.04 LTS"){
+        Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){
+            Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.")
+        }
+    }
+    Deployment_Node(bb2, "bigbank-web*** x4", "Ubuntu 16.04 LTS"){
+        Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){
+            Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.")
+        }
+    }
+    Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){
+        Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){
+            ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
+        }
+    }
+    Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS") {
+        Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c") {
+            ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
+        }
+    }
+}
+
+Rel(mobile, api, "Makes API calls to", "json/HTTPS")
+Rel(spa, api, "Makes API calls to", "json/HTTPS")
+Rel_U(web, spa, "Delivers to the customer's web browser")
+Rel(api, db, "Reads from and writes to", "JDBC")
+Rel(api, db2, "Reads from and writes to", "JDBC")
+Rel_R(db, db2, "Replicates data to")
+
+UpdateRelStyle(spa, api, $offsetY="-40")
+UpdateRelStyle(web, spa, $offsetY="-40")
+UpdateRelStyle(api, db, $offsetY="-20", $offsetX="5")
+UpdateRelStyle(api, db2, $offsetX="-40", $offsetY="-20")
+UpdateRelStyle(db, db2, $offsetY="-10")
+```
\ No newline at end of file
diff --git a/docs/diagrams/c4-dynamic.md b/docs/diagrams/c4-dynamic.md
new file mode 100644
index 0000000..66acada
--- /dev/null
+++ b/docs/diagrams/c4-dynamic.md
@@ -0,0 +1,18 @@
+``` mermaid
+C4Dynamic
+title Dynamic diagram for Internet Banking System - API Application
+
+ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
+Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
+Container_Boundary(b, "API Application") {
+    Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.")
+    Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.")
+}
+Rel(c1, c2, "Submits credentials to", "JSON/HTTPS")
+Rel(c2, c3, "Calls isAuthenticated() on")
+Rel(c3, c4, "select * from users where username = ?", "JDBC")
+
+UpdateRelStyle(c1, c2, $textColor="red", $offsetY="-40")
+UpdateRelStyle(c2, c3, $textColor="red", $offsetX="-40", $offsetY="60")
+UpdateRelStyle(c3, c4, $textColor="red", $offsetY="-40", $offsetX="10")
+```
\ No newline at end of file
diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 0000000..c3fe801
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,7 @@
+---
+title: Glossary
+---
+
+# Glossary
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..2d3485a
--- /dev/null
+++ b/docs/index.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.
diff --git a/docs/introduction-and-goals.md b/docs/introduction-and-goals.md
new file mode 100644
index 0000000..f7d9da2
--- /dev/null
+++ b/docs/introduction-and-goals.md
@@ -0,0 +1,19 @@
+---
+title: Introduction and Goals
+---
+
+# Introduction and Goals
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Requirements Overview
+
+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.
+
+## Quality Goals
+
+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.
+
+## Stakeholders
+
+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.
diff --git a/docs/js/custom.js b/docs/js/custom.js
new file mode 100644
index 0000000..e69de29
diff --git a/docs/quality-requirements.md b/docs/quality-requirements.md
new file mode 100644
index 0000000..4dbba81
--- /dev/null
+++ b/docs/quality-requirements.md
@@ -0,0 +1,15 @@
+---
+title: Quality Requirements
+---
+
+# Quality Requirements
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Quality Tree
+
+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.
+
+## Quality Scenarios
+
+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.
diff --git a/docs/risks-technical-debts.md b/docs/risks-technical-debts.md
new file mode 100644
index 0000000..35de10b
--- /dev/null
+++ b/docs/risks-technical-debts.md
@@ -0,0 +1,19 @@
+---
+title: Risks and Technical Debts
+---
+
+# Risks and Technical Debts
+
+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.
diff --git a/docs/runtime-view.md b/docs/runtime-view.md
new file mode 100644
index 0000000..3d5f3e6
--- /dev/null
+++ b/docs/runtime-view.md
@@ -0,0 +1,19 @@
+---
+title: Runtime View
+---
+
+# Runtime View
+
+xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx xxxxxxx xxxxxx xxxxxx xxxxx.
+
+## Scenario 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.
+
+## Scenario 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.
+
+## Scenario 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.
diff --git a/docs/solution-strategy.md b/docs/solution-strategy.md
new file mode 100644
index 0000000..dc1776a
--- /dev/null
+++ b/docs/solution-strategy.md
@@ -0,0 +1,19 @@
+---
+title: Solution Strategy
+---
+
+# Solution Strategy
+
+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.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..e0fd1c2
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,78 @@
+site_name: Software Architecture
+site_url: https://dassiorleando.github.io/software-architecture-documentation-template
+copyright: MIT
+theme:
+  name: mkdocs-material-adr
+  features:
+    - toc.follow
+    - navigation.footer
+    - navigation.path
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.top
+    - navigation.indexes
+    - navigation.instant
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      toggle:
+        icon: material/brightness-7
+        name: Switch to Dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to Light mode
+extra:
+  consent:
+    title: Cookie consent
+    description: >- 
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+extra_css:
+  - css/custom.css
+extra_javascript:
+  - js/custom.js
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+nav:
+  - Getting Started:
+    - index.md
+    - introduction-and-goals.md
+    - architecture-constraints.md
+    - context-scope.md
+    - solution-strategy.md
+    - building-block-view.md
+    - runtime-view.md
+    - deployment-view.md
+    - cross-cutting-concepts.md
+    - Decision Records: decisions/0000-index.md
+    - quality-requirements.md
+    - risks-technical-debts.md
+    - glossary.md
+  - Architecture Decisions:
+    - decisions/0000-index.md
+    - decisions/0001-sample.md
+plugins:
+  - search
+  - mkdocs-material-adr/adr
+  - macros:
+      modules:
+        - mkdocs_macros_adr_summary
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..542c8dd
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,7 @@
+
+# Requirements for core
+mkdocs-material~=9.5.46
+
+# Requirements for plugins
+mkdocs-material-adr~=1.1.1
+mkdocs_macros_adr_summary~=1.0.0