Executive summary

In today's rapidly changing software world, the ability to adapt and evolve the software architecture is crucial for success.
The readiness for change is a key factor in ensuring a product can meet evolving business and product requirements in the high-tech industry.

However, uncontrolled architecture drifts and erosions pose significant risks to a product's success.
These drifts can result in the loss of expected extensibility and hinder the adoption of a product as the user base grows.
Identifying and addressing these drifts is often done through complex and time-consuming manual architecture reviews, relying on experienced architects to assess the software architecture.

Despite the importance of manual reviews, they have limitations in terms of efficiency and coverage.
Human factors can influence the identification of architectural issues, leading to inconsistencies and potentially missing critical problems.

To overcome these challenges, there is a need for automated solutions that can detect architecture drift and erosion more effectively.
By leveraging automated tools and processes, organizations can achieve better outcomes in terms of identifying and preventing architectural issues.

This white paper explores the concept of detecting architectural gaps with automation.
It covers the impact of architecture drift and erosion on the business, the limitations of manual reviews, and the benefits of automating architecture checks.
Additionally, it discusses specific considerations related to compliance, data security, DevOps, and more when evaluating architecture review solutions.
The paper also provides use case scenarios to illustrate what automated architecture checks can look like in practice.

By adopting automated architecture review solutions, organizations can improve their ability to identify and address architectural gaps, ensuring the stability, scalability, and maintainability of their software systems.

Detecting Architectural Gaps with Automation

Please read this paper before proceeding to the next chapters.

You will gain insights into the following:

• Understanding architecture drift and erosion: Learn what architecture drift and erosion are and how they can impact the business. Gain an understanding of the risks and challenges associated with uncontrolled architectural changes.
• Manual inspections and their limitations: Explore the role of dependency analysis, peer reviews, and other manual inspections in detecting architectural issues. Understand why manual reviews, while important, may not be the ideal solution due to their limitations.
• The need for automated architecture review: Discover the benefits of automating architecture checks and how they can complement manual reviews. Learn how automation can provide more efficient and comprehensive detection of architectural gaps.
• Considerations for evaluating architecture review solutions: Explore specific considerations to keep in mind when evaluating architecture review solutions. Topics covered include compliance, data security, DevOps integration, and more.
• Use case scenarios: Gain insights into what automating architecture checks may look like through a series of example use case scenarios. Understand how automation can be applied in practical situations to enhance architecture review processes.

By reading this paper, you will develop a deeper understanding of architecture drift and erosion, the limitations of manual reviews, the benefits of automation, and important considerations when evaluating architecture review solutions.

Solution requirements

This section outlines the requirements for implementing the solution.
It is important to note that these requirements are not exhaustive and can be extended based on the specific needs of the project.
The requirements are categorized into solution modes and inputs, solution integration and user interaction, and solution output with quality attributes like modifiability, extendibility, and configurability.

Solution modes

The proposed solution should support the following modes:

• Standalone application: The solution should be designed to run as a standalone application, allowing it to be executed on demand without any dependencies on the target environment. This mode provides flexibility for manual execution of the solution.

• Integration with CI/CD pipeline: The solution should have the capability to integrate seamlessly into a CI/CD pipeline as a separate step. This mode enables regular assessment of the architecture within the automated pipeline.

In the context of the CI/CD mode, the following features should be supported:

• Initial architecture reference: The solution should allow setting an initial architecture as a reference point. Any deviations from this reference architecture should be identified as architecture drifts.

• Drift reporting and approval process: When a drift is detected, the solution should provide an option to approve or decline the changes with comments. The description of the change should include an impact analysis, allowing the user to understand the cost associated with the proposed change.

• Documenting drifts and erosion: The solution should provide the ability to save the documentation that describes drifts or erosions. This documentation can be useful for future analysis and reference. It should be easily accessible for review and analysis purposes.

• Integration with popular CI/CD tools: The solution should be easily integrated with widely used CI/CD tools such as Jenkins, Bamboo, etc. This ensures compatibility and seamless integration into existing CI/CD workflows.

Solution inputs

The proposed solution can accept various inputs, including:

• Code from the solution under review: The solution should be able to analyze and process code files from the software being reviewed.

• Configuration from the solution under review: Configuration files used by the software should be compatible with the solution to extract relevant information.

• Software design from UML designing tools: The solution should support importing software designs created using UML (Unified Modeling Language) tools. This allows for a comprehensive analysis of the software's architectural design.

• Database scripts and database configuration: The solution should be capable of working with database scripts and configurations, enabling analysis of the database layer in the software.

These inputs collectively provide the necessary information for the solution to perform its analysis and evaluation of the software architecture.

Solution integration

Integration of the proposed solution with various tools and systems allows for a comprehensive analysis of software architecture.
Here are the integration possibilities mentioned:

• Offline UML designing tools: The solution can be integrated with offline UML designing tools like OmniGraffle and Microsoft Visio. This integration enables the import of UML diagrams created using these tools for analysis and evaluation.

• Online UML designing tools: Integration with online UML designing tools such as Enterprise Architect, LucidChart, Draw.IO, PlantUML, and Gliffy.com provides the ability to import UML diagrams created in these platforms. This expands the range of tools that can be used for software design and analysis.

• Source control management systems: Integration with source control management systems like SVN and Git allows the solution to access code and configuration files directly from the repository. This ensures that the latest version of the software is analyzed, and any changes made to the codebase are taken into account.

By integrating the solution with these tools and systems, users can leverage existing software design and version control workflows to enhance the effectiveness of the automatic review process.

As an example of the input code could be the code written in C# using microservices architecture.
The other example could be the code written in JavaScript for multi-tier applications.

The example of configuration might be the description of nodes used in deployment.
Another example could be the configuration of VPN networks and API gateways.

The example of input software design can be description of interfaces saved in Enterprise Architect.

User interaction

The proposed solution provides a web interface that allows users to interact with it from a desktop computer.
The interface is designed to accommodate the content and functionality required for software architecture analysis, making it unsuitable for mobile devices such as smartphones or tablets due to their smaller screen size.

There are two types of users supported by the solution: administrators and architects.
Administrators have the capability to configure the system according to the intended use.
They can set up various parameters and customize the solution to meet specific requirements.

Architects, on the other hand, have the ability to run the proposed solution for analysis and review the results.
They can initiate the analysis process and examine the generated analysis reports.
The solution provides dashboards that display relevant metrics and software architecture status, such as the count of components and dependencies.
These dashboards offer a comprehensive overview of the software architecture and assist architects in understanding its structure and characteristics.

By catering to both administrators and architects and offering dedicated functionalities for each role, the solution ensures that users can effectively configure and utilize the system for software architecture analysis and evaluation.

Solution output

The proposed solution offers two formats for presenting the output: text-based (plain text or table) and graphic.

The text-based format, particularly in a table structure, provides users with detailed information about identified issues.

The table typically includes the following columns:

• Level of issue: Indicates the severity or significance of the issue.
• Issue priority: Specifies the priority level assigned to address the issue.
• Issue description: Provides a clear description of the identified issue.
• Suggested way to fix the issue: Offers recommendations or guidelines on how to resolve the issue effectively.

Additionally, the table format includes separate sections that list various dependencies, such as frameworks, libraries, APIs, databases, technology stack (languages), and application layers.
Each section provides a comprehensive inventory of the associated components used in the application.
This allows users to gain insights into the technologies and resources utilized and understand their impact on the architecture.

Furthermore, the solution enables users to request inventories of specific elements, including languages, frameworks, libraries, and databases, at any time.
This feature provides a convenient way to access comprehensive information about the software application's underlying components and dependencies.

The graphic format is utilized to visually represent the software architecture, including

• the holistic application architecture,
• diagrams of all services,
• and data flows.

Both offline and online UML diagramming tools are employed to save and document the extracted software architecture.
This graphic format allows users to annotate and tag components and inventory items using user-defined keywords.

Here's an example of a graphic output:

In the graphic representation above, four services and one database are identified within the software architecture.
The diagram clearly illustrates the relationships between these components and the direction of communication between them.

Modifiability and extendibility

Modifiability and extendibility are essential attributes for the proposed solution.
The solution should be designed in a way that allows for easy extension and the addition of new features, such as new checks or levels.
The scope of the solution should not restrict its ability to adapt to different project needs and requirements.

By default, the solution should include a set of checks to verify the target architecture.
However, for projects that already have an established architecture governance process, users should have the flexibility to extend and customize the set of checks according to their specific needs.

Given the existence of various Static Code tools like Coverity and SonarQube that handle low-level checks like indentation and formatting, it would be redundant to implement those checks in the proposed solution.
Instead, the solution should focus on providing value through higher-level architectural checks and analysis.

Configurability

Configurability is a crucial aspect of the proposed solution, allowing users to tailor the system to their specific needs and environment.
The following configuration items can be supported:

• Solution Mode: The solution should offer different modes of operation, and users can configure the preferred mode during the deployment stage. For example, it can be run as a standalone application or integrated into the CI/CD pipeline.

• Path for Architecture Documents: Users should be able to specify the path to read architecture documents from offline UML design tools like OmniGraffle or Microsoft Visio.

• Online UML Design Tool API: The solution can integrate with online UML design tools like Enterprise Architect, LucidChart, Draw.IO, PlantUML, or Gliffy.com. Users need to provide the API address to access and update architecture documents online.

• Source Control Management System Configuration: The proposed solution should be able to integrate with version control systems like SVN or Git. Users will configure the settings to access code and configuration from these repositories.

• Database Addresses for Data Layer Observation: Users should provide the addresses of databases to observe the data layer and perform analysis on database scripts and configurations.

• CI/CD Tool Integration: The solution should seamlessly integrate with popular CI/CD tools like Jenkins or Bamboo. Configuration options should enable easy integration into the CI/CD pipeline for regular architecture assessment.

• Report Plugins Configuration: Users should be able to configure report plugins, including their format and storage settings. This allows customization of the generated reports based on individual preferences and requirements.

By providing these configurability options, the proposed solution becomes versatile and adaptable, meeting the specific needs and workflows of different projects and organizations.