Tracking architecture decisions

Name Architecture Decision Records
Summary Strategic cooperation whereby different projects, groups or communities, while each operating independently, agree to collaborate and evolve an ecosystem collectively. They anticipate each other’s needs, align roadmaps, features, etc.
Keywords Architecture, Software, Non-functional requirements, Documentation, Collaboration
Type Best-practice
FSDL position Architecture design / Architecture notebook

This is a placeholder best-practice that was inspired by @Ryuno-Ki who has experience in using them.

Thanks for opening this thread.

In the past I have worked with in professional settings. It proved to be useful using the wiki software that was provided by the client.

The elements are crucial:

  • Title (a summary to make it easier to search)
  • Timestamp (allows for assessing the relevance)
  • Status (e.g. proposed, accepted, rejected, deprecated, superseded)
  • Context (what is the environment in which a decision has to be made, constraints and similar)
  • Decision (out of several options which one is the way the team agreed to continue with?)
  • Consequences (what are the next action items caused by the decision)

Writing ADRs allows us to have a track record about decisions that were made in the past. Since I’m working in web frontend industry, this could be the decision on using SCSS vs. CSS-Modules vs. CSS-in-JS for example.

There were instances that made us reconsider a decision because the environment changed and we had to adapt. Having written down the context and possible options saved us time on research.

Institutionalising knowledge is also beneficial for team transitions (easier to onboard new people, less reliant on a single person and so on).

I can highly recommend adopting this practice.

1 Like

I looked at some templates e.g. the ones listed in this repo by Joel Henderson. There’s quite a big difference in formality, the amount of fields and information to track. Some lend themselves more for large organizations, multiple teams, complex software. For instance Decision record template by Jeff Tyree and Art Akerman would be overkill for most FOSS projects. There’s a big risk that the formality will lead to the documentation chore not happening.

But your field list looks reasonable. The Decision record template by Michael Nygard appeals to me, mostly free-form text, only tracking paragraphs:

  • Title
    • Status: E.g. proposed, accepted, rejected, deprecated, superseded.
    • Context: What is motivating this decision or change?
    • Decision: What is the change that we’re proposing and/or doing?
    • Consequences: What becomes easier or more difficult to do because of this change?

A slight variation is the Decision record template for Alexandrian pattern (a long-used pattern). Yet another variation is Decision record template by Paulo Merson, where some additional process is described:

Usage guidelines

  • Each ADR is a plain text, 1-2 page document
  • ADRs should be numbered
  • ADRs should be stored within each software project repo
  • Create a separate repo for crosscutting ADRs
  • Track ADRs in the backlog
  • Review ADRs
  • Create ADRs for significant design decisions

The ADR markdown template itself is just as simple, having free-form text and a few paragraph sections. Here’s an example (click to expand):

ADR 005: Use a CQRS Pattern

ADR 005: Use a CQRS Pattern

We have a microservice architecture with several REST services that would need to read and write data.
Sometimes it’s difficult to design those services to do both tasks efficiently.
In the Farmacy Food system, the design of writes (commands) is primarily concerned with the integrity of data and business rules,
whereas the design of reads (queries) has performance (response time) as a key requirement.


We will use the CQRS pattern applied to microservices with this design:

  • an independently deployed service takes care queries. It reads data from a query view that is optimized for data reads.
    (“Optimized” means using DB technologies and techniques that favor performance, such as: NoSQL, denormalized view, memory cache, sharding, replication.)
  • an independently deployed service takes care of commands. It may be a REST service that gets POST commands or a reactive service
    that subscribes to a pub-sub topic and gets messages that updates the primary database for the scope of that service.
  • a batch component (example: K8S cron job or logic activated by database-triggered events) synchronizes the data between
    the primary database and the query views. The frequency of data synchronization varies–it can be trigger-based,
    every 5 minutes, every hour, …, once a day, etc.

In our design, we have used CQRS for:

  • Inventory
  • Orders
  • Subscription


We expect that the app will issue far more query requests than commands. For example, the inventory is checked in many customer
operations, such as looking at a catalog meal item.
The CQRS pattern is used to address performance (response time)
requirements on queries.




  • The CQRS pattern uses data replication for query views and hence eventual consistency. Therefore, query services may
    operate on stale data (during the interval between data synchronization from primary db and query view).
  • Need to monitor data synchronization tasks, with notification and proper action in case of failure.

Only a bit more elaborate template is MADR, or Markdown Any Decision Records. It comes in a long and short form, listing options and where the long form indicates per option what is good and what is bad. MADR has several tools available for management (both for the CLI and a GH integration to make ADR management easier).