When significant changes are planned for a system, it is vital to know what its current architecture is actually capable of. You might be facing the implementation of a new feature or integration, a regulatory change, or a decision to modernize the system. At other times, system development may have slowed down and costs increased without any obvious reason.

An architecture review is an assessment by an external expert on how the software is built and what its structure allows it to achieve. The review helps identify potential problems and risks, and enables informed decisions about the system’s future before committing to major development projects.

A quality report answers a different question than an architecture review

Many organizations already use code quality tools. However, these answer a different question than the one for which a review is typically commissioned.

A code quality tool tells you if there is a flaw on an individual line. Management, however, wants to know what the system as a whole can handle. It is difficult to get an answer to the latter from a thousand line-specific observations. Furthermore, the absence of observations does not prove the architecture is functional. A system can be clean by mechanical metrics and yet have a structure where even a small addition is laborious.

How is an architecture review conducted?

At Reflector, we begin an architecture review with a discussion. What is the system being used for now? What are the plans for it, and what are the concerns? This determines where the assessment will focus.

After that, we run the code through our own automated analysis tools. These quickly provide an overall picture and highlight areas that warrant a closer look. The code is processed in our own environment and is not sent to external services.

We interpret and verify the tool results ourselves. We distinguish genuine problems and assess their severity based on how the system is used. If necessary, we clarify any ambiguous points with the developers.

Finally, we compile the findings into a report and review them with you.

What is covered in an architecture review

Size and structure. How much source code, tests, configuration, and generated code are there, and how is the code distributed across different parts? Which parts depend on what, are the module boundaries holding, and are there circular dependencies between parts? We also look for any module that almost everything else relies on. This reveals why a small change can ripple through many places.

Libraries and security. What third-party libraries does the project use, and do they have known vulnerabilities? At the same time, we see which technologies the system relies on. Additionally, static analysis searches the code for known patterns of security flaws.

Modifiability. We assess how easily and safely changes can be made to the system. The amount of test code relative to the source code provides the first impression. Without tests, changes are riskier and slower to implement. We also measure where logic has accumulated to such an extent that changes become heavy and error-prone.

Known pitfalls. We look for bugs and performance issues that recur from one project to another. For example, a save operation might not reach the database because a transaction is incorrectly defined, or hundreds of separate queries are made to the database when one would suffice.

A review takes from a few days to a couple of weeks, depending on the size of the system. We require read access to the code from the client and a little time for background briefing.

What you get from an architecture review

The report answers three questions:

1. Is the code in good shape? We tell you directly whether the system can withstand the changes planned for it.

2. If not, what is missing? In a format that can be taken forward. For example: The boundaries between application layers are not holding, causing maintainability to erode. One module has grown to cover a large part of the system, and almost every change depends on it. There are many tests, but they do not cover the areas where future changes will hit.

3. What should be done and in what order? Recommendations in order of priority, based on what will facilitate development the most.

Observations refer to a specific point in the code and include a suggested fix. This allows the team to see the basis of the assessment and verify it themselves. Additionally, we provide an overview of the code, which may include a size distribution, module map, or dependency diagram. These also facilitate discussion with various system stakeholders.

Developers often know where the problems lie, but it can be difficult to demonstrate them to management. After the review, the team and decision-makers have a shared, code-based understanding of the system.