Ahmad Alfy

Blog about front-end development and the web

Architecture Decision Records

01 Jan 2021

A couple of years ago I learned about Architecture Decision Records (ADRs) from Technology Radar and how they help software development teams document the architecture decisions they take during software design. In the beginning, I had an impression that these kinds of documents are suitable for projects of a certain size where a software architect is needed, but I was wrong.

I was excited to try it because it didn’t require too much effort. I will have to write down a markdown file for every architecturally significant decision I take. That file should answer a couple of questions that I already think about most of the time. This time I will have to document it. The document is simple, it consists of the following:

  • The decision we need to take.
  • Status of that decision whether it’s a proposal, accepted decision, rejected, or superseded.
  • Context, which is an explanation of the problem and all the circumstances around it.
  • Considered options; listing of all the considered options with the pros, cons, and impact of each.
  • The decision that will be taken and all the reasons favoring that decision.
  • The consequences of taking that decision whether it’s positive or not.

The following is an example of the document that I wrote when I decided to use PostCSS over Sass in an Angular based project:

# Choosing Pre/Post processor for project X

## Status


## Context

PostCSS is far more robust than Sass and other pre-processors. We've utilized PostCSS in several
projects and it significantly improved our output. Our workflow and tools are optimized around it
and our teams are very familiar with it. Sadly PostCSS is not supported by default using Angular
CLI so we will have to wire its configuration manually.

## Considered options

1. Sass; comes by default with Angular.
2. PostCSS; will have to configure it but we will get LTR/RTL automatically.

## Decision

We will use PostCSS with the following plugins:

. Logical properties and values. We will get multi-directional layouts automatically
. `:dir` pseudo class
. Nested
. Retina background image

## Consequences

### Positive Consequences

. We automatically get RTL support from a single codebase.

### Negative Consequences

. We had to switch from `@angular-devkit/build-angular:browser` to
`@angular-builders/custom-webpack:browser` and provide custom configuration path for Webpack.
That's one more dependency

. PostCSS parser doesn't create the proper hash for the images parsed in the component's style.
We have to switch the background image declarations to `src/assets/styles` instead. Problem is
prominent in SSR.

. SSR always detects the language as `en-US` even if the route is an Arabic one. This lead to
serving the wrong `lang` and `dir` attribute on the `html` tag. This is rectified quickly by 
the browser on runtime though.

More details on this [closed issue](https://github.com/angular/angular-cli/issues/12075).
. Logical properties doesn't work out of the box. The scoped styles from Angular adds a hash
to the `[dir]` attribute. To overcome this we need to use a special selector called `:host`
like the following:

`/* This will not work */`
`element { margin-inline-start: 15px; }`

`/* This will work */`
` element { :host & { margin-inline-start: 15px; } }`

This was one of the earliest records I wrote. I felt this record is valuable because:

  • It shows my analysis to my colleagues and the points I consider when I am making this decision.
  • It documents the results in detail, explaining how it impacts the code we write.
  • It highlights the negative results with links to existing issues for further follow-up and discussion.

The first instruction we had on this project’s readme file was to go read the ADRs. Over two years, we had people joining and leaving that project, no one was asking why did we pick PostCSS or why the selectors they wrote didn’t work. It was all documented. I started to encourage my colleagues to write ADRs as well and the results came back very positive. It helped everyone reason their decisions. The records were being shared across different projects that use similar stack and technology saving us all time and effort and helped with knowledge transfer.

It’s worth mentioning that even rejected decisions should be documented. It’s important to keep that in mind, you’re not only documenting your accepted decisions. This helps others from proposing the same things over and over without a valid reason.

ADRs have proven to be ver beneficial to us and I would definitely recommend it. If you want to try it I would suggest you follow the simplest form which is to write markdown files lying side by side with your source code. I’ve included several links in the resources section below.


comments powered by Disqus