Tracking Software Architecture Decisions

Maybe this sounds familiar to you: joining a new software engineering company or moving from your current team to a different team and being asked to keep evolving an existing product. You realized that this solution is using an uncommon architectural pattern in your organization. Let’s say it is applying event sourcing for persisting the state of the domain aggregates. If you like event sourcing; but do not like it for the specific nature of the product, most likely, it wouldn’t have been your first choice. As a software architect, you start to find the rationale behind that solution, find documentation with no success, and ask the software engineers that do not have the answer you were looking for.

This situation might have a relevant negative impact. Software architectural decisions are key and drive the overall design of the solution, impacting maintainability, performance, security, and many other “-alities.” There is no perfect software architecture decision designing architectures is all about trade-offs, understanding their implications, sharing their impacts with the stakeholders, and having mitigations to live with them.

Therefore, having a well-established process for tracking those kinds of decisions is key for the success and proper evolution of a complex software product, even more, if that product is created in a highly regulated environment. However, today’s software is designed and developed following agile practices, and frameworks, like SAFe, try to scale for large solutions and large organizations. It is key to maintain a good balance between the decision-making process and agility, ensuring the former does not become an impediment to the latter.

Architecture Decision Records (ADRs)

My organization uses Architecture Decision Records (ADRs) to register and track architectural decisions. ADRs is a well-known tool with many different writing styles and templates like MADR. Now the question is how to ensure the ADRs are in place and with the right level of governance. As we will see below, ARDs are written in markdown and managed in a git repository, where everybody can contribute, and a consensus shall be reached to accept them and move forward with the architecture decision. 

For that, we have created the following process:

First Swimlane

In this process, the first swimlane includes team interactions that triggers architecture concerns, requiring a supportive architecture decision. Those concerns will come mainly from:

• Product definition and refinement: At any level (e.g., epic, capability, feature, stories), architecture concerns are identified. Those concerns shall be captured by the corresponding software architect.
• Feedback from agile teams: Architecture decision-sharing sessions and inspect and adapt sessions (e.g., system demos, iteration reviews, and retrospectives) are moments where architecture concerns can be identified. It is key to understand if agile teams are facing problems with the architecture decisions made so far; if the teams do not believe in the architecture, it will not be materialized.

Second Swimlane

The second swimlane involves mainly the architecture team and optionally technical leads from agile teams. This team will meet regularly in an architecture sync meeting where the following steps will be taken:

Step 1

Architecture backlog management: Concerns are registered in the architecture backlog as enablers, prioritized, assigned. The first task associated with enablers is creating the Architecture Decision Record.

Step 2

Gather inputs and perform the analysis: The architect assigned to work on the ADR will gather additional inputs from the stakeholders, colleagues, and agile team members, working on spikes with the team to go deeper into the analysis when needed. During this state, the architect will collaborate closely with the agile teams to perform the required analysis and alternatives evaluation of several backlog enablers and spikes that might be needed.

Step 3

Work on the ADR: The outcome of the previous state is used to write the ADR, condensing the decisions to be taken, the context around the decision, alternatives assessed, final decisions, and consequences, both positive and tradeoffs. The ADR is created in the source control system. In our case, using GitHub because it has a main branch for accepted ADRs and a feature branch for the ongoing ADR.

Step 4

Publish ADR: Once the ADR is ready for decision, a pull request is created, assigning a reviewer all the relevant stakeholders. Revision is not limited to architects but is open to a wider audience, like software engineers from agile teams, product owners, product managers, etc.

Third Swimlane

The third swimlane goal is agreeing on the decision under discussion. In this context, the ADR is reviewed by the architecture team during their regular meetings (e.g., architecture alignment/architecture board). Ideally, the solution shall be reached by consensus, but if an agreement isn't reached in the expected timelines, the designated software architect (depending on the decision level, it can be an enterprise architect, solution architect, or system architect) will make the final decision.

Step 5

Review ADR on Architecture alignment: The ADR owner provides a brief presentation of the ADR to their mates that will provide feedback until the next alignment.

Step 6

Collect and review comments: ADR reviewers add comments to the pull request, providing feedback to the ADR owner that replies to the comments and applies the corresponding adjustments. This approach ensures all the concerns during the ADR definition are tracked and available for review at any time in the future by simply accessing the ADR’s pull request.

Step 7

The designated Software Architect makes the final decision: This state is only needed if, for any reason, there is no agreement between architects and engineers. At some point in time, there should be accountability in the decision, and this accountability resides in the corresponding Software Architect. Ideally, this state will not be needed, but it is also true that a decision cannot be delayed forever.

Step 8

Involve stakehoders: It will be bad news if you reach this state, which is there as a safeguard in case the decision taken by the architect is clearly wrong. Stakeholders are involved in the decision process to reevaluate the ADR and reach final agreement.

Step 9

Sign ADR: Once the ADR is accepted by the majority of reviewers, it is merged to main. From this point, the ADR becomes official, and the corresponding decision shall be realized by the engineering teams, leveraging analysis and spikes performed in step 2. ADRs are now immutable.

Step 10

Superseded former decision: If the new decision replaces a previously accepted ADR, it can be modified to change its status to “Superseded,” indicating by which ADR it is replaced.

Conclusion

This process might look a bit cumbersome, but it should not take more than a few days to decide once the analysis phase (step 2) is completed. The pros of such a process outweigh the cons by having a clear architecture decision history, easy to track from well know tools (e.g., GitHub, GitLab), and providing the highest value for a long-lasting solution.

Also, it is important to note that this is a collaborative process that should help balance intentional architecture with an emergent design by the involvement of agile team members in the architecture concerns identification, decision analysis phase, and feedback sharing.

I hope this can help you improve how architecture decisions are made and evolve. I am happy to hear from you in the comments!