feat: add architectural decision records

README.md

@@ -11,7 +11,7 @@
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
-A minimal, opinionated template for modern Python projects -- featuring Poetry packaging, Ruff for linting and formatting, justfile, pytest testing with code coverage upload to codecov, MkDocs documentation with configuration for Read The Docs, pre-commit hooks, GitHub Actions CI, GitHub issue and pull request templates and automated semantic releases.
+A comprehensive, opinionated template for modern Python projects -- featuring Poetry packaging, Ruff for linting and formatting, justfile, pytest testing with code coverage upload to codecov, MkDocs documentation with configuration for Read The Docs, pre-commit hooks, GitHub Actions CI, GitHub issue and pull request templates, architectural decision record (ADR) templates and automated semantic releases.
 
 The goal is to help you start writing code immediately without having to spend time deciding what tools or conventions to use.
 
@@ -49,6 +49,8 @@ The goal is to help you start writing code immediately without having to spend t
 - Docs ([MkDocs](https://www.mkdocs.org/) + [mkdocstrings](https://mkdocstrings.github.io/)): [mkdocs.yml](mkdocs.yml)
     - Automated deployment to `gh-pages` branch via GitHub action: [.github/workflows/docs-pages.yaml](.github/workflows/docs-pages.yaml)
     - Configuration for Read The Docs integration: [.readthedocs.yaml](.readthedocs.yaml)
+    - Template for [documenting architectural decisions](https://adr.github.io/): [docs/architecture/adr/template.md](docs/architecture/adr/template.md).
+    - ADR to explain the rationale for using ADRs: [docs/architecture/adr/001-use-architectural-decision-records.md](docs/architecture/adr/001-use-architectural-decision-records.md).
 - Release automation via GitHub action from [release-please](https://github.com/googleapis/release-please): [.github/release-please-config.json](.github/release-please-config.json)
 - Citation metadata: [CITATION.cff](CITATION.cff)
 - BSD-3-Clause: [LICENSE](LICENSE)
@@ -107,6 +109,10 @@ Hook definitions: [.pre-commit-config.yaml](.pre-commit-config.yaml)
     - [docs/reference.md](docs/reference.md) (autogenerated API documentation from docstrings via mkdocstrings).
     - [docs/tutorials.md](docs/tutorials.md)
     - [docs/explanation.md](docs/explanation.md)
+- Architecture pages
+    - Template for [documenting architectural decisions](https://adr.github.io/): [docs/architecture/adr/template.md](docs/architecture/adr/template.md).
+    - ADR to explain the rationale for using ADRs: [docs/architecture/adr/001-use-architectural-decision-records.md](docs/architecture/adr/001-use-architectural-decision-records.md).
+    - Index of ADRs: [docs/architecture/adr/index.md](docs/architecture/adr/index.md).
 
 ## 🔄 Releases
 
@@ -126,7 +132,12 @@ Managed by release-please: ([conventional commits](https://www.conventionalcommi
 │   └── unit/
 │       └── test_greet.py           # Example unit test (replace with real tests)
 ├── docs/                           # MkDocs content (Diátaxis layout)
-│   ├── index.md
+│   └── architecture                # Content on architectural decisions
+    │    └── adr                    # Architectural decision records
+    │        ├── NNN-*.md           # ADR files
+    │        ├── index.md           # Index of ADRs
+    │        └── template.md        # Template to use for new ADRs
+    ├── index.md
 │   ├── reference.md                # Auto-generated via mkdocstrings
 │   ├── tutorials.md
 │   ├── explanation.md
@@ -164,6 +175,7 @@ Use [conventional commit](https://www.conventionalcommits.org/) messages (feat:,
 - Lint & format clean
 - Tests pass
 - Docs build without warnings
+- ADR drafted for architecturally significant changes
 
 Suggestions and improvements to this template are very welcome — feel free to open an issue or pull request if you spot something that could be refined, added or removed.
 

docs/architecture/adr/001-use-architectural-decision-records.md

@@ -0,0 +1,82 @@
+# ADR-0001: Use Architectural Decision Records
+| | |
+| ---| ---|
+| **Status** | 🟢 Accepted |
+| **Created**  | 2025-10-12 |
+| **Last Updated**  | 2025-10-12 |
+| **Deciders** | Gemma Danks |
+| **Tags** | docs |
+
+---
+
+## Context
+
+Architectural decisions are design choices that have a significant impact on one or more architecture qualities (e.g. modifiability, maintainability, observability, testability, scalability, interoperability, extensibility, portability). These decisions shape both the current state of a project and its long-term trajectory. Over time, the rationale for these decisions can get lost if they are not written down. One certainty in software development is that there will at some point be a need, or a desire, to change and adapt to new technologies and best practices.
+
+Without knowing why a decision was made, there is a risk that future developers will not feel empowered to make changes. This will lead to the accumulation of technical debt when working around the current architecture in the short-term and, in the long-term, will make the project obsolete. Conversely, there may be a very good reason for sticking to the original decision but if future developers are not aware of this reason they may make changes that must later be reverted, wasting time and effort. Nygard refers to these two alternatives as "blind acceptance" and "blind reversal" in [a 2011 blog post on documenting architectural decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), which we recommend reading for additional context.
+
+Another force to consider, at the time of writing in 2025, is the rapid adoption of AI tools for software development. A future developer may defer to an AI coding assistant or agent to recommend changes. Unless there is an AI-readable record of the rationale for earlier decisions, these tools are more likely to recommend reversing those they see as suboptimal. If this record exists, however, AI can be used more effectively to evolve a project and help onboard new developers (e.g. by providing summaries, answering questions and explaining the rationale behind certain choices).
+
+## Problem Statement
+
+How do we share the rationale for architectural decisions with future human or AI developers so that they can make more informed choices that ensure the continuity and evolvability of the project?
+
+## Options Considered
+
+|    Option    | Description                    | Maintainability | Knowledge Retention | Traceability | AI Usability | Effort | Discoverability | Overall score | Notes |
+|--------------|--------------------------------|-------------|-----------------|-------------| ----- | ------|------| ----| ---|
+| **Weight**   | -                              | 1  | 2 | 1  | 1  | 1 | 1 | - |
+| **ADR**      | Architectural Decision Record  | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | 21 |  |
+| **Docs**     | Architecture page in docs      | ✅ | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | 20 |  |
+| **README**   | Architecture section in README | ✅ | ✅ | ⚠️ | ⚠️ | ✅ | ⚠️ | 19 |  |
+| **Diagrams** | Flowcharts of decision trees   | ⚠️ | ⚠️ | ❌ | ❌ | ⚠️ | ⚠️ | 11  |  |
+
+✅ = 3 (good), ⚠️ = 2 (acceptable), ❌ = 1 (poor)
+
+Maintaining a collection of [Architectural Decision Records](https://adr.github.io/) (ADRs) has been standard practice in industry, beginning the 1990s and popularised by [Nygard's 2011 blog post](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). ADRs are small text files, written in Markdown, that describe the context, the decision, and the consequences of the decision (both good and bad). They ensures a detailed decision history that is human and AI-readable. Several templates for ADRs have been developed and are in use. These vary in the number of sections and level of detail and can be customised. They are easy to maintain and provide the best way to retain history of rationale for decisions but there is a larger effort involved in creating and reviewing them.
+
+Informal documentation in the project README or docs requires less effort and is easy to maintain but the history is mostly in the git commits and is harder to find and evaluate by humans. Using the documentation rather than the README makes the information more discoverable.
+
+Flowcharts provide a human-friendly visual overview but are more difficult to maintain and not as AI-friendly (although flowcharts as code is AI-friendly and might work well as a supplement if they are kept up-to-date).
+
+## Decision Outcome
+
+We will keep a collection of [Architectural Decision Records](https://adr.github.io/) using a template based on [MADR](https://adr.github.io/madr/), which extends the template proposed by Nygard to include evaluating alternatives, which provides additional valuable knowledge to share with future developers and facilitates a re-evaluation at a later date.
+
+The **title** in the ADR file will use the pattern `ADR-NNN: <Verb> <Object> [optional qualifier]`, where NNN is a zero padded three digit number (e.g. ADR-001: Use Architectural Decision Records). ADRs will be numbered sequentially and monotonically. Numbers will not be reused.
+
+**Metadata** listed under the title will include: the status of the ADR (🟡 Proposed, if not yet agreed upon and/or under review / 🟢 Accepted if agreed upon / 🔵 Superseded by ADR-NNN if another decision reverses/replaces it), the date created, date last updated, a list of decision-makers and a list of tags.
+
+A **Context** section will describe the forces at play in value-neutral language, stating the facts on the background to a decision.
+
+A **Problem Statement** will summarise the challenge faced and, where possible, articulate it as a clear question to be answered.
+
+An **Options Considered** section will include a decision matrix scoring each of the options considered against the key drivers behind the decision. To avoid false precision, a simple scoring system will be used to rate an option as either good (✅), ok (⚠️) or poor (❌). Emoticons will be used to provide human readers with a quick visual overview. These are also readable by current AI tools, such as ChatGPT, and keeping a legend with numerical scoring improves AI-readability. Optional weights will represent the relative importance of drivers and an overall score used to rank the options. A short description will supplement and summarise this decision matrix.
+
+The **Decision Outcome** section states the final decision and the justification based on the results of the decision matrix evaluation. It is stated in full sentences, with active voice.
+
+A **Consequences** section describes the resulting context, after applying the decision. This should describe both the positive and negative impacts of the decision on the project and should also list any unknowns or risks (and optionally what should be done to mitigate these risks).
+
+The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer and in a way that maximises its usefulness for AI assistants.
+
+We will keep ADRs in the project repository under `docs/architecture/adr/`. The filename will match the ADR title without the `ADR` prefix, all lowercase and `-` replacing spaces, e.g. `001-use-architectural-decision-records.md`. A template in this directory (`template.md`) will used for all new ADRs for consistency.
+
+If we change a decision at a later date, we will keep the old ADR but mark it as superseded. This way it is available for additional context.
+
+## Consequences
+
+Future developers will have clarity over why architecturally significant decisions were made and feel empowered to reverse these decisions as technologies and best practices evolve. AI assistants will gain the context needed to make better suggestions and recommendations. Developers will also benefit from using AI to summarise and explain earlier decisions. This will also be a powerful way to quickly onboard new developers, particularly as the collection of ADRs grows.
+
+There will be additional effort required for developers to create and review ADRs but this will pay off in the long-run by reducing the risk of wasting time and effort changing decisions that should not be changed or repeating mistakes that sharing more knowledge would have prevented. Effort can be reduced by using AI assistants to draft and review ADRs (this ADR and the template can be provided as context).
+
+## Confirmation
+
+Developers will be prompted to confirm that they have checked for relevant ADRs when opening a PR. If they are making changes that includes a design choice they will be prompted to create a new ADR with status "Proposed", which must be reviewed and accepted before merging any code changes.
+
+## Links
+
+| Type | Links |
+| -----| ------|
+| **ADRs**   | |
+| **Issues** | |
+| **PRs**    | |

docs/architecture/adr/index.md

@@ -0,0 +1,5 @@
+# Architectural Decision Records
+
+| ADR | Status | Summary |
+|-----|---------|----------|
+| [ADR-001: Use Architecture Decision Records](001-use-architectural-decision-records.md) | 🟢 Accepted | Use ADRs to explain the rationale behind architecturally significant design choices for future developers and AI assistants |

docs/architecture/adr/template.md

@@ -0,0 +1,71 @@
+# ADR-NNN: short title for solved problem and found solution
+| | |
+| ---| ---|
+| **Status** |  🟡 Proposed / 🟢 Accepted / 🔵 Superseded by ADR-NNN |
+| **Created**  | YYYY-MM-DD |
+| **Last Updated**  | YYYY-MM-DD |
+| **Deciders** | Name |
+| **Tags** | template |
+
+---
+
+## Context
+
+Describe the background and constraints written for future human **and AI** developers.
+
+## Problem Statement
+
+Summarize the main challenge in one or two sentences.
+Then, phrase the decision explicitly as a question.
+
+## Options Considered
+
+Use the table below to evaluate your options against key decision drivers.
+1.	**Define your drivers** — the forces, constraints, or architectural qualities that matter most (e.g. scalability, maintainability, observability, budget, effort).
+Add each driver as a column name.
+2.	**List your options** — add each considered solution as a row.
+3. **(Optional) Assign weights** to drivers to show relative importance.
+4.	**Describe each option** — one line summary.
+5.	**Score each option** for how well it satisfies each driver using the legend: ✅ = 3 (Good) ⚠️ = 2 (Acceptable) ❌ = 1 (Poor)
+6.	**Compute overall score**:
+```
+overall score = (Driver1 weight × Driver1 score)
+              + (Driver2 weight × Driver2 score)
+              + ...
+              + (DriverN weight × DriverN score)
+```
+7. **(Optional) Add short notes** on the main pros and cons for each option.
+8. **(Optional) Sort the rows** according to the overall score (best fit at the top)
+
+|  Option  | Description | Driver 1 | Driver 2 | Driver N | Overall score | Notes |
+|----------|-------------|-------------|-----------------|-------------| ----- | ------|
+| **Weight**   | - | 1 | 1 | 1 | - |
+| **A** |  |  |  |  |  | |
+| **B** |  |  |  |  |  | |
+| **C** |  |  |  |  |  | |
+
+✅ = 3 (good), ⚠️ = 2 (acceptable), ❌ = 1 (poor)
+
+## Decision Outcome
+
+We will use **Option X** because...
+
+Justify your choice using the results of the decision matrix above. Describe evidence to support the scoring.
+
+## Consequences
+
+* Good, because...
+* Bad, because...
+* Unknowns/risks
+
+## Confirmation
+
+How will you ensure this ADR is implemented and enforced?
+
+## Links
+
+| Type | Links |
+| -----| ------|
+| **ADRs**   | |
+| **Issues** | |
+| **PRs**    | |

mkdocs.yml

@@ -12,6 +12,10 @@ nav:
   - How-to Guides: how-to.md
   - Reference: reference.md
   - Explanation: explanation.md
+  - Architecture:
+      - ADR Index: architecture/adr/index.md
+      - ADR-001: architecture/adr/001-use-architectural-decision-records.md
+      - Template: architecture/adr/template.md
 
 extra_javascript:
     - javascript/readthedocs.js