Conducting an Effective Software Architectural Review: An Introductory Guide

In today’s rapidly evolving technology landscape, ensuring your software architecture is robust, scalable, and aligns with your business goals is paramount. Whether you’re a seasoned software architect or a technology leader, conducting a software architectural review is critical to providing valuable insights and setting a clear roadmap for your future tech strategy.

This guide, informed by practical experiences working with clients ranging from startups to one of the UK’s biggest retailers, offers a structured approach to conducting such reviews. I am sharing an experience involving a client who embarked on a modernisation program for their sizeable online e-commerce website. They aimed to ensure they were still on the right trajectory after three years of work. My team and I, composed of senior front-end consultants, worked alongside the client’s team to review the work that had taken place and how it aligned with the business’s current goals. This guide aims to turn that practical experience into a blueprint that you can follow in your own context.

Phase 1: Analysis

The Analysis phase focuses on understanding the business goals and how they relate to the architecture. This is crucial as it allows you to define the north star for the entire modernisation effort.

1. Define Business Goals

Start by asking your client their goals for the modern platform — why do they want to modernise it? What are the pain points they are trying to alleviate? This foundational step ensures the review is driven by business needs, not just technology trends.

2. Rank and Size Goals

Once you have the list, work with key business stakeholders to rank and relatively size their goals. This should lead to a pie chart showing the relative importance of each goal. This step provides a clear visualisation of the priorities and allows for better alignment of resources.

3. Map Goals to Architectural Characteristics

Carry out a collaborative exercise to map each goal to architectural characteristics, or “-ilities”. This step bridges the gap between business goals and technical requirements. For example, if a business goal is to “make it easier to recruit new software engineers”, the relevant characteristics might be simplicity, learnability, and developer experience.

4. Define Metrics for Each Characteristic

Research and decide on the best metrics to measure each architectural characteristic. For instance, you might decide that the best way to assess developer experience is to create a questionnaire that includes a version of the “Net Promoter Score” question. This ensures you have a quantifiable way to measure success.

5. Measure Current Architecture

Once you can measure each characteristic, gather data for the current architecture. This could involve using the developer questionnaire, metric analysis tools, accounts to calculate the cost, and various reports from internal departments. This gives you a baseline to compare future improvements.

6. Define Target Metrics

Using the business goals and their relative sizing, along with your understanding of best practices and industry standards, define target numbers for each metric. At this point, you should have a mapping of the business goals through to empirical measurements to assess architectural changes. This provides clear, objective targets for the modernisation effort.

Phase 2: Architect

In the Architect phase, the team dives deep into the existing architecture to understand it thoroughly and identify risk areas and potential improvements.

1. Hands-On Development

To truly understand the challenges and advantages of the existing architecture, engage in hands-on development. It’s one thing to look at a system from the outside and another to work with it directly. This gives you a practical understanding of the system and helps you identify pain points.

2. Perform an In-Depth Technical Review

Review the current system using architectural diagrams, the codebase, documentation, etc. This allows you to understand how the system has been built and operated and provides an opportunity to identify any areas that may not align with the business’s goals that you previously identified.

3. Conduct Risk Storming

Follow a structured risk-storming activity, such as the one outlined by Richards and Ford in their book “Fundamentals of Software Architecture”. This allows everyone involved in the project to highlight areas of the architecture they feel pose a risk to the architectural characteristics that are most important to the business.

4. Discuss Mitigation Possibilities

As the final part of the risk-storming activity, talk about potential mitigations. Create a risk matrix that highlights the highest risk areas of the architecture and then allow everyone to contribute ideas to mitigate those risks.

5. Create Proof of Concepts (PoCs)

Using the risk mitigation ideas and the risk matrix, work to create PoCs that test each hypothesis. This is a collaborative process where the team assesses the ideas, reviews the implementation options, and provides feedback to create a cycle of improvement.

6. Create a Consolidated PoC

Once the team is satisfied that each risk has been thoroughly investigated and the most viable implementation found to mitigate it as best as possible, create a single PoC that takes all the changes and provides a single view of them working together. This helps confirm that all changes can work together and provides a single picture of what a re-platforming might look like.

7. Assess the PoC

After you have a single PoC, assess it against the original metrics you defined and see how close it can meet the target values for each metric. This clearly shows how the proposed changes could impact the system and whether they align with the business goals.

By following these steps, you ensure that the architectural review is comprehensive and focuses on areas of the architecture that are most important to the business. Moreover, the practical experience of working with the existing architecture and creating PoCs provides invaluable insight into potential future changes.

Phase 3: Conclusion

The Conclusion phase is where the work from the Analysis and Architect phases come together to provide a comprehensive view of the current state, future state, and the path to get there.

1. Present the PoC

Start this phase by presenting the proof of concept (PoC) and the architecture diagrams representing the new architecture. It’s important to give stakeholders a visual and practical understanding of the proposed changes.

2. Showcase the Metric Analysis

Next, show the business stakeholders the metric analysis with the current, target, and the values the PoC achieved. This highlights progress and clearly compares the current and potential future state.

3. Replay the Process

Playback the entire process you’ve been through and confirm any unanswered questions and metrics you’ve been unable to assess. This ensures everyone involved is on the same page and comprehensively understands the work done.

4. Define Next Steps

Finally, confirm the following steps: creating a migration plan that allows the teams to move from the current architecture to the new one. This gives everyone precise tasks and goals to work towards after the review.

Remember, conducting a software architectural review is a comprehensive process that requires clear communication, careful planning, and in-depth technical understanding. However, the payoff in terms of alignment with business goals, improved developer experience, and overall software quality makes it a valuable exercise for any software team.