Book a Demo
search icon

Using Architecture Decision Records to guide your architecture choices

6 min read

Written by: Bruno Oliveira

publication inner img

In modern software development, the only constant is change: business needs evolve over time, features are added, expanded or removed accordingly, and development teams doing the work themselves are also subject to change over time. All this makes the whole software development process more complex and uncertain.

As such, it is becoming increasingly important for software development teams to find ways to manage complexity and ensure that both current and future development work is done while taking into account all the decisions that have been made before.

By doing so, all the changes that have happened over time can be leveraged today, so that better decisions can be made tomorrow.

One of the ways that the SIG development team found effective in enabling better decision-making is the use of Architecture Decision Records – ADRs, for short.

We will look at what an ADR is, as a general concept, as it’s not really new nor unique to SIG, and then we will detail how we “implement it” in practice for our specific context.

What is an ADR, and why use it?

As discussed above, any production-grade software product will always be backed by a shifting landscape behind the scenes: changes in business requirements, changes to the teams that write and maintain the software, and external changes, like new framework and language versions that open up many possibilities and deprecate others.

With so many changes, it can become impossible for a team to keep track of everything taking place in all the different areas that make up a software product.

As a result, something needs to be introduced within the team’s development process that allows teams to manage all this inherent complexity in a way that is effective, has low overhead, and can actually be kept somewhere.

In this way, it can be consulted when needed or desired, and can be tracked over time. Ideally, kept in version control so that it can evolve and “sit next” to the actual code, where architectural decisions will more likely be materialized, why? 

Because architectural decisions are usually made taking the current software architecture into account. When code changes, and we want to document how and why it needed to change, it’s only logical to keep these close together.

By keeping this decision-making process in version control next to the code, we benefit from locality and visibility. It turns out that such a standardized way of doing this already exists and is in practice described and used by the software engineering community formally called an “Architecture Decision Record”.

Looking at ThoughtWorks’s nice description on their Technology Radar on this exact topic, we can describe a “lightweight” version of an Architecture Decision Record as a technique for capturing important decisions with their context and consequences.

The structure of an ADR can vary depending on various aspects, such as your specific goals when using it, the level of maturity of the team that wants to implement it, etc., but as a general structure, the image below is a good starting point:

Figure 1 – Example structure of a lightweight ADR (Source: RedHat)

Let’s quickly dissect the above structure and look at the usefulness of each field and how they, as a whole, provide a cohesive view of all the significant architectural decisions made during the life of a project. Let’s take a look at how to structure an ADR for a particular example.

Small case study: at a certain point in time, it was decided that a specific DB table T would not be queried directly anymore in favour of using a service S which proved to be more reliable and easier to test.

Based on the above case study, let’s see what an ADR would look like:

While not all lightweight ADRs have to follow this exact structure, these sections are usually present in an ADR. They provide a great overview of the tandem between software and the business itself while being extremely valuable as a resource for sharing knowledge, upskilling the entire team, and onboarding new people.

How we use ADRs at SIG

Now that we’ve looked at ADRs in general and how they can bring several benefits to a software development team, let’s look at how an ADR is written in practice at SIG.

There can be many ways to materialize an ADR, but for our use, and since we use lightweight ADRs, we decided to take the simplest approach that works.

At the top level of our backend repository, we have a docs folder, and one level down we have another folder named architecture_decision_record. By having it as a folder in our top-level repository, we immediately take advantage of the benefits of version control, so every change we make to our ADRs is documented in our version control systems, which is a great advantage for traceability and history.

Each individual ADR is created as a Markdown document that follows a specific template that is very similar to the one shown above: the convention when naming a newly created markdown file is the format: XXX – <a descriptive title highlighting the decision> where XXX is a number so all the decisions can be ordered, and the title very generically describes the purpose and content of the document.

As for the structure of the document itself, it contains six main sections that we leverage, many of which overlap with what is described above: date, status, context, decision and consequences.

The SIG template we use also includes an additional field called “Other options considered”. As the name implies, this is a dedicated section of an ADR where we look at different options that we have considered before making a final decision. The value of this section is that we become broader and more open-minded in terms of what is possible within our tech stack, what we can do or cannot do, and it’s also a way to stretch the limits of our own codebase, where sometimes performance improvements or optimizations can be hiding “in plain sight”.


We hope this blog showed you the value of adopting ADRs within your own software projects and teams. It is a simple, low-overhead way of documenting architectural decisions that offer many additional benefits, like traceability of decisions over time, trade-offs, and how the codebase and business change over time, and serves as a historical record of a project’s life cycle. By adopting it, you also help newcomers to the team immediately gain context that might otherwise be lost by being considered “institutional knowledge”. Making these decisions visible will increase team and project resilience over time and make it easier to make better and more well-informed decisions to guide the projects and teams to their maximum potential.


Bruno Oliveira

Software Developer

image of author
yellow dot illustration

Let’s keep in touch

We'll keep you posted on the latest news, events, and publications.

  • This field is for validation purposes and should be left unchanged.