Architecture Decision Records

During project and product development, software engineering teams need to make architectural decisions to reach their goals. These decisions can be technical or process-related.

• Technical: Deciding to use JBOSS Data Grid as a caching solution vs Amazon Elasticache or deciding to use the AWS Network Load Balancer (NLB) vs AWS Application Load Balancer (ALB).
• Process: Deciding to use a Content Management portal for sharing documents or project-related artifacts. 

Making these decisions is a time-consuming and difficult process, and it's essential that teams justify, document, and communicate these decisions to relevant stakeholders.

Three major anti-patterns often emerge when making architectural decisions:

• No decision is made at all out of fear of making the wrong choice.
• A decision is made without any justification, and most of the time, people don’t understand why it was made and the use case or the scenario that has been considered. This results in the same topic being discussed multiple times.
• The decision isn’t captured in an architectural decision repository, so team members forget or don’t know that the decision was made.

What Is an ADR?

An Architecture Decision Record (ADR) is a document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision.

When Will You Write an ADR?

ADRs are typically written when a significant architectural decision needs to be made, such as when selecting a new technology, framework, or design pattern or when making a trade-off between different architectural goals, such as performance, scalability, and maintainability. 

ADRs are also useful for documenting decisions that have already been made to ensure that the rationale behind them is clear to all members of the development team. ADRs also ensure that you are aligned with the organization’s IT strategies.

ADRs typically include information such as the problem being addressed, the options considered, the decision made, the reasons behind the decision, and any relevant technical details. They may also include any implications or risks associated with the decision, as well as any future work that may be required because of the decision.

Writing ADRs can help to promote transparency and collaboration within a development team, as well as provide a valuable resource for future developers who may need to understand the reasoning behind past decisions.

Best Practices When Writing an ADR

When writing an Architecture Decision Record (ADR), it's important to follow some best practices to ensure that the ADR is clear, useful, and easy to understand. Here are some best practices for writing an ADR:

• Start with a clear title: The title of the ADR should be clear and concise and should summarize the decision being made.
• Define the problem: Begin the ADR by clearly defining the problem or challenge that the decision is addressing. This helps to provide context for the decision and ensures that everyone understands the problem being solved.
• Describe the decision: Clearly describe the decision that has been made, including the alternatives considered and the reasons for selecting the chosen option. This should include any trade-offs or compromises that were made, as well as any technical details that are relevant.
• Explain the rationale: Provide a clear and detailed explanation of the rationale behind the decision. This should include any relevant business or technical considerations, as well as any risks or potential drawbacks.
• Document any implications: Document any implications of the decision, including any dependencies on other parts of the system, any impacts on performance or scalability, and any risks or issues that may arise because of the decision.
• Keep it concise: ADRs should be concise and easy to read. Avoid including unnecessary information or technical jargon and focus on providing clear and concise explanations of the decision-making process and its rationale.
• Keep it up-to-date: ADRs should be kept up-to-date as the project progresses. If new information or considerations arise that impact the decision, the ADR should be updated to reflect these changes.

By following these best practices, ADRs can provide a clear and useful record of important architectural decisions and help to ensure that everyone on the team is aligned and informed about the reasoning behind those decisions.

Example ADR

Now that we have defined what an ADR is and the best practices to be followed when writing an ADR let’s try and put those best practices in writing an ADR.

For writing an example ADR, we will try and document one of the solutions described in the blog, migrating unstructured data (files) from on-premises storage to AWS. In the blog, there are three scenarios and a solution for each of those scenarios. For this ADR example, we will pick the solution for Migrating from NAS to AWS using AWS DataSync.

Title: Migrating from NAS to AWS using AWS DataSync

Status: Accepted

Date: 6th October 2023

Context:
Application A picks up incoming files from an Application X, processes them and 
generates data files that are 50–300 GB. That, then, becomes the input for another 
Application Y to consume. The data is shared by means of an NFS Storage accessible to 
all three applications.

Application A is being migrated to AWS and the Applications X and Y continue to remain 
on-premises. We used AWS Elastic File System (EFS) to replace NFS on AWS. However, that
makes it difficult for the applications to read/write from a common storage solution, 
and network latency slows down Application X and Application Y


Decision:
We will use AWS DataSync Service to perform the initial migration of nearly 1 TB of 
data from the on-premises NFS storage to AWS EFS

AWS DataSync can transfer data between any two network storage or object storage. These
could be network file systems (NFS), server message block (SMB) file servers, Hadoop
distributed file systems (HDFS), self-managed object storage, AWS Snowcone, Amazon 
Simple Storage Service (Amazon S3) buckets, Amazon Elastic File System (Amazon EFS)
file systems, Amazon FSx for Windows File Server file systems, Amazon FSx for Lustre 
file systems and Amazon FSx for OpenZFS file systems.
 
To solve the need for the applications to read/write from a common storage solution and
address the network latency involved during read/write operations across the Direct 
Connect, we scheduled a regular synchronization of the specific input and output folders
using the AWS DataSync service between the NFS and EFS. This means that all three 
applications look at same set of files after the sync is complete.

Consequences:
Positive
• No fixed/upfront cost and only $0.0125 per gigabyte (GB) for data transferred.

Negative
• Syncs can be scheduled at minimum one-hour intervals. This soft limit can be 
modified for up to 15-minutes intervals, however, that leads to performance issues 
and subsequent sync schedules getting queued up, which forms a loop.
• Bidirectional Syncs were configured to run in a queued fashion. That is, only 
one-way sync can be executed at a time. Applications will have to read the files after
the sync interval is completed. In our case, files are generated only one time per day,
so this challenge was mitigated by scheduling the read/writes in a timely fashion.
• AWS DataSync Agent (virtual appliance) must be installed on a dedicated VM 
on-premises.

Compliance:

Notes:

 	Author(s): Rakesh Rao and Santhosh Kumar Ramabadran
	Version: 0.1

Changelog:
0.1: Initial proposed version

While the above is one format, an ADR can be created in any format agreed with the stakeholders. It could be as simple as a Word document, a spreadsheet, or a presentation.

When Will You Not Write an ADR?

While Architecture Decision Records (ADRs) can be helpful in documenting important architectural decisions, there may be some cases where writing an ADR is not necessary or appropriate. Here are a few examples:

• Minor decisions: If a decision has minimal impact on the architecture of the system or is relatively straightforward, it may not be necessary to write an ADR. For example, if a team decides to update a library to a newer version, and the update is expected to have little impact on the overall architecture, an ADR may not be necessary.
• Temporary decisions: If a decision is expected to be temporary or is only applicable to a specific context or situation, it may not be necessary to write an ADR. For example, if a team decides to implement a temporary workaround for a bug, and the workaround is not expected to be a long-term solution, an ADR may not be necessary.
• Routine decisions: If a team makes routine decisions that are not particularly significant or require little discussion or debate, an ADR may not be necessary. For example, if a team decides to follow an established design pattern or uses a commonly used technology, an ADR may not be necessary.
• Existing documentation: If the decision has already been documented elsewhere, such as in project requirements or design documentation, it may not be necessary to create an ADR specifically for that decision.

Ultimately, the decision of whether to write an ADR depends on the significance of the decision and the context in which it is being made. If the decision has a significant impact on the architecture of the system, involves trade-offs or alternatives, or is likely to have long-term implications, it is generally a good idea to create an ADR to document the decision-making process.

Alternatives to ADR

While Architecture Decision Records (ADRs) are a common and effective way to document important architectural decisions, there are several alternative approaches that can be used depending on the specific context and needs of a project. Here are a few alternatives to ADRs:

• Code comments: One simple alternative to ADRs is to use code comments to document architectural decisions directly within the codebase. This can be a useful approach for smaller projects or for teams that prefer a more lightweight approach to documentation. However, code comments can become difficult to manage and may not provide enough context or detail for more complex decisions.
• Design documents: Design documents can provide a more comprehensive and detailed way to document architectural decisions. These documents can include diagrams, flowcharts, and other visual aids to help explain the architecture of a system. However, design documents can be time-consuming to create and may become outdated as the project evolves.
• Wikis or knowledge bases: Wikis or knowledge bases can be used to document architectural decisions in a more flexible and searchable way than ADRs. This approach can be particularly useful for large or complex projects, as it allows teams to easily find and reference information related to specific architectural decisions. However, wikis and knowledge bases can also become difficult to manage and may require additional effort to keep up-to-date.
• Meetings and discussions: Another approach to documenting architectural decisions is to hold regular meetings or discussions to review and document decisions. This approach can be useful for teams that prioritize face-to-face communication and collaboration but may not be as effective for remote teams or those with members in different time zones.

Ultimately, the best approach to documenting architectural decisions depends on the specific needs and context of a project. Teams should consider factors such as project size, team size, and communication preferences when deciding which approach to use.