✨ Add ADR

.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+name: Publish & Deploy ADR
+on:
+  push:
+    branches:
+      - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+  contents: read
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  publish-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: "14"
+
+    - name: Install Log4Brains
+      run: npm install -g log4brains
+
+    - name: Publish ADR
+      run: log4brains build --basePath /${GITHUB_REPOSITORY#*/}
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: './_site'
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.log4brains.yml

@@ -0,0 +1,5 @@
+project:
+  name: VerticalSliceArchitecture
+  tz: Australia/Sydney
+  adrFolder: ./docs/adr
+  packages: []

docs/adr/20240513-use-log4brains-to-manage-the-adrs.md

@@ -0,0 +1,22 @@
+# Use Log4brains to manage the ADRs
+
+- Status: accepted
+- Date: 2024-05-12
+- Tags: dev-tools, doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which tool(s) should we use to manage these records?
+
+## Considered Options
+
+- [Log4brains](https://github.com/thomvaill/log4brains): architecture knowledge base (command-line + static site generator)
+- [ADR Tools](https://github.com/npryce/adr-tools): command-line to create ADRs
+- [ADR Tools Python](https://bitbucket.org/tinkerer_/adr-tools-python/src/master/): command-line to create ADRs
+- [adr-viewer](https://github.com/mrwilson/adr-viewer): static site generator
+- [adr-log](https://adr.github.io/adr-log/): command-line to create a TOC of ADRs
+
+## Decision Outcome
+
+Chosen option: "Log4brains", because it includes the features of all the other tools, and even more.

docs/adr/README.md

@@ -0,0 +1,35 @@
+# Architecture Decision Records
+
+ADRs are automatically published to our Log4brains architecture knowledge base:
+
+🔗 **[VerticalSliceArchitecture ADRs](https://sswconsulting.github.io/VerticalSliceArchitecture)**
+
+Please use this link to browse them.
+
+## Development
+
+If not already done, install Log4brains:
+
+```bash
+npm install -g log4brains
+```
+
+To preview the knowledge base locally, run:
+
+```bash
+npm log4brains preview
+```
+
+In preview mode, the Hot Reload feature is enabled: any change you make to a markdown file is applied live in the UI.
+
+To create a new ADR interactively, run:
+
+```bash
+npm log4brains adr new
+```
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

docs/adr/index.md

@@ -0,0 +1,36 @@
+<!-- This file is the homepage of your Log4brains knowledge base. You are free to edit it as you want -->
+
+# Architecture knowledge base
+
+Welcome 👋 to the architecture knowledge base of the SSW Vertical Slice Architecture Template.
+You will find here all the Architecture Decision Records (ADR) of the project.
+
+## Definition and purpose
+
+> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
+> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.
+
+An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order.
+Moreover, maintaining this documentation aims at:
+
+- 🚀 Improving and speeding up the onboarding of a new team member
+- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
+- 🤝 Formalizing the decision process of the team
+
+## Usage
+
+This website is automatically updated after a change on the `main` branch of the project's Git repository.
+In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
+You can browse the ADRs by using the left menu or the search bar.
+
+The typical workflow of an ADR is the following:
+
+![ADR workflow](/l4b-static/adr-workflow.png)
+
+The decision process is entirely collaborative and backed by pull requests.
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

docs/adr/template.md

@@ -0,0 +1,61 @@
+# {{ SHORT TITLE }} <!-- short title of solved problem and solution -->
+
+- Status: {{ STATUS }} <!-- optional: draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](yyyymmdd-xxx.md) -->
+- Deciders: {{ DECIDERS }} <!-- optional: list everyone involved in the decision -->
+- Date: {{ LAST MODIFIED YYYY-MM-DD }} <!-- optional. YYYY-MM-DD when the decision was last updated. To customize the ordering without relying on Git creation dates and filenames -->
+- Tags: {{ TAGS }} <!-- optional: space and/or comma-separated list of tags -->
+
+Technical Story: {{ TECH STORY }} <!-- optional: description | ticket/issue URL -->
+
+## Context and Problem Statement
+
+{{ CONTEXT }} <!-- required: Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in the form of a question. -->
+
+## Decision Drivers <!-- optional -->
+
+- {{ DRIVER 1 }} <!-- e.g., a force, facing concern, … -->
+- {{ DRIVER 2 }} <!-- e.g., a force, facing concern, … -->
+- … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+1. {{ OPTION 1 }}
+2. {{ OPTION 2 }}
+3. {{ OPTION 3 }}
+
+## Decision Outcome
+
+Chosen option: "{{ OPTION 1 }}", because {{ JUSTIFICATION }} <!-- e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below) -->.
+
+### Consequences <!-- optional -->
+
+- ✅ {{ POSITIVE CONSEQUENCE 1 }}
+- ❌ {{ NEGATIVE CONSEQUENCE 1 }}
+
+## Pros and Cons of the Options <!-- optional -->
+
+### {{ OPTION 1 }}
+
+{{ DESCRIPTION }} <!-- optional: example | description | pointer to more information | … -->
+
+- ✅ {{ ARGUMENT A }}
+- ❌ {{ ARGUMENT B }}
+
+### {{ OPTION 2 }}
+
+{{ DESCRIPTION }} <!-- optional: example | description | pointer to more information | … -->
+
+- ✅ {{ ARGUMENT A }}
+- ❌ {{ ARGUMENT B }}
+
+### {{ OPTION 3 }}
+
+{{ DESCRIPTION }} <!-- optional: example | description | pointer to more information | … -->
+
+- ✅ {{ ARGUMENT A }}
+- ❌ {{ ARGUMENT B }}
+
+## Links <!-- optional -->
+
+- {{ LINK }} <!-- example: Refined by [xxx](yyyymmdd-xxx.md) -->
+- … <!-- numbers of links can vary -->