The Ultimate Guide to Architectural Decision Records

Introduction to ADRs with examples, templates, and managing instruments

A path of books
Picture by Laura Kapfer on Unsplash

Architectural choice information (ADRs) doc essential architectural selections made together with their context and penalties. They had been first launched by Michael Nygard in a 2011’s blog post.

An ADR normally consists of a brief textual content file describing a particular structure choice. You may write them in plain textual content, AsciiDoc/Markdown format, or use a wiki web page template.

Let’s see a few of the important advantages of utilizing ADRs:

  • They seize important details about the software program that may be reviewed at any time.
  • They will act as an efficient means to doc the software program structure. The ADR highlights why a specific choice was made. It additionally describes trade-off evaluation, for example, selecting efficiency over scalability.
  • If the builders wish to perceive why a specific expertise was chosen for a given mission, they will discover the reason within the ADR. This reduces inner debates. Builders have the vital considering, so it’s essential to allow them to perceive the whys. This results in extra belief inside the groups.
  • They assist new staff members to get accustomed to the architectural mind-set. Newcomers will perceive what facets play essentially the most important roles within the infrastructure. They are going to get an thought of what has been achieved previously.
  • If somebody desires to suggest a brand new expertise, it could end up that the subject has already been mentioned and rejected. The reason being within the ADR. So, they will make investments their time in trying to find a brand new resolution.
  • Keep transparency inside and out of doors of the groups. Anybody within the subject can learn in regards to the choice course of. This fashion, totally different teams can study from one another.

ADRs needs to be concise and easily written.


The title accommodates a brief phrase describing the architectural selections.


Programming language and framework for our frontend.


The standing may be:

  • Proposed (beneath overview)
  • Accepted (accepted and prepared for implementation)
  • Outmoded (outmoded by one other choice)


The context explains why we have to decide. It additionally describes the alternate options together with the professionals and cons.


We have to select a programming language for our frontend. It must be appropriate for net and cellular purposes. Our UI wants numerous detailed customization.


The choice describes the justification for why the actual resolution was accepted. It has extra emphasis on the why reasonably than the how.

Instance (That is simply an illustration of a technical choice; it’s OK should you don’t agree with it):

We’ll use Flutter as a frontend framework.

We thought-about the next frameworks:


Flutter — quick, offers many UI parts out-of-the-box that hastens the event without having to implement the parts ourselves. It has a built-in materials design. It’s well-documented regardless that it’s a younger framework.

React Native — we now have to implement a lot of the parts ourselves. The documentation is just not very detailed. The general efficiency is not so good as Flutter’s.


The implications part accommodates details about the general affect of an architectural choice. Each choice has trade-offs. That’s why it’s essential to incorporate the evaluation to offer a transparent image.


It has a studying curve: Builders should study Dart programming language to make use of the Flutter framework.

You could be asking your self: ought to I at all times write ADRs? Not essentially, however listed here are some factors that may assist you to determine if it’s price creating an ADR:

  • Do you hear folks continuously asking the identical questions: Why was this specific choice made? Why did the architects select this expertise over this one? The present implementation has trade-offs, resembling decrease efficiency, so why did they go for this type of structure?
  • Do you wish to suggest a change that impacts the entire software program? It’s an acceptable strategy to begin a dialogue the place the professionals and cons may be reviewed.


You may retailer the ADRs in your Git repository in a separate ADR folder. Nevertheless, not everybody may need entry to Git, for instance, enterprise analysts, product homeowners, and so on. Due to this fact, this isn’t essentially the most optimum selection. The best method is to retailer the ADRs in a shared Wiki web page the place everybody can see them.


If you happen to’re uncertain find out how to begin, don’t fear as a result of quite a few ADR templates exist already. Essentially the most broadly used one is by Michael Nygard:

Try this collection on GitHub for extra concepts and kinds.


There are numerous instruments that can assist you preserve monitor of your ADRs. Here’s a handy, lightweight software that can assist you with that:

This Python-based software exhibits the ADR on a neighborhood net server or as generated static content material.

ADR Viewer official demo

A full demo may be discovered right here:

If you have already got some ADRs, contemplate making a log. The Adr-Log tool produces an architectural choice sign off of ADRS:

Screenshot from the unique supply:

To work with ADR logs, I like to recommend a command-line software known as Adr-tools. It runs instructions to create ADRs primarily based on a template, for instance, like this one:

An ADR Template

Congratulations! You discovered the rules of ADRs. Now why, when, and find out how to use them. I additionally listed just a few helpful instruments to handle ADRs.

I hope that you just’ve discovered one thing new right this moment. Thanks for studying, and see you subsequent time!

More Posts