Architecture Decision Records

Created on: September 03, 2023Modified on: September 16, 2023

This page is a good intro of what ADRs are about.

Some thoughts of my own below:

What is it?

Several small text files describing a single decision and the rationale. It should contain:

context
decision
consequences

Examples

Some dummy examples below:

0001-record-architecture-decisions.md

Markdown

# 1. Record architecture decisions

Date: 2022-09-17

## Status

Accepted

## Context

We need to record the architecture decisions made on this project to ensure we preserve the context of our choices.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard in [documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR tool, see [Nat Pryce's adr-tools](https://github.com/npryce/adr-tools).

0002-programming-language.md

Markdown

# 2. Programming Language

Date: 2022-09-17

## Status

Accepted

## Context

As the building block for the technology we need to choose the programming languages used in different domains.

## Decision

- We will adopt Clojure for reasons that are best described in [Gene Kim's Love Letter to Clojure Post](https://itrevolution.com/love-letter-to-clojure-part-1/).
- It also supports Frontend (with ClojureScript), Backend (Clojure on JVM), Database (with Datomic and EDN), and Scripts using babashka.
  - This is a powerful combo for productivity because the same language is used everywhere.

## Consequences

Prefer Clojure at all costs before introducing another language.

Then have other decisions, even if they seem small:

0003-continuous-integration.md
0004-linting.md
0005-testing.md
0006-scripting.md
0007-database.md
0008-test-runner.md
0009-frontend-routing.md
0010-parsing-library-from-to-json.md
0011-date-library.md

This create what I think is a good friction, where before developing something you have to document the decision and by doing that it actually helps you to think more about the problem.

It's also great to arrive at a team that has this because you can read the entire thing and understand where they are at.

I also think it's valuable to have a North Star text file containing things the team should strive for. Example:

# North Star Principles

These are some of the core ideas that we believe and we want this software to reflect that.

- We should prefer data over calculations, and calculations (pure functions) over actions (side effects).
- Production code and test code have the same level of importance. They should flow together during development.
- Ideally functions should have docstrings.
- Prefer unit tests over integration tests, and integration tests over UI tests.