Keep Your Architecture Specification Consistent with Your Code Base

While there is no precise, commonly agreed-on definition of what constitutes a software architecture, it is understood that a software system’s architecture is defined by its decomposition into building blocks and their inter-dependencies. For each pair of components, the architecture defines if and in what way the two components interact which each other. An architecture conformance analysis evaluates how well the implemented architecture matches the specified architecture. Identifying architecture violations using the conformance analysis is a required step for the maintainability of the code base. The release 1.5 of our tool Teamscale adds features that allow the conformance analysis to be better integrated in the development cycle of a project. This article describes the basic concepts needed to understand the editing of architecture and conformance analysis as performed by Teamscale.

Document a concept of the intended architecture

Documenting the intended architecture of a project is easy using the architecture editor of Teamscale. The following conceptual steps can be done using a graphical interface.

  • Define components (of the software system) and policies. Policies define the access rights between components, whether or not code corresponding to one component is allowed to access code of a second component. For example, we might define two components «UI» and «Core», create an «ALLOW» policy from «UI» to «Core» (since the user interface component is allowed to access code of the core component). No policy is specified from «Core» to »UI», thus implicitly the core component should not depend on user interface controls.
  • Map architecture components to code entities. Different code entities are programming language dependent. For a C# project, Teamscale takes as input source code files *.cs and allows the use of type names as code entities. We can map all the types from the namespace Common\.UI\..* to the «UI» component and all the types from the namespace Common\.Core\..* to the «Core» component. In general, the mappings are defined using regular expressions.

The screenshot below shows the Architecture view of Teamscale in «edit mode». The «Scheduler» component is highlighted and the bottom of the screenshot shows the component maps to types from the package core/scheduler/.*.


After finishing the edits of the architecture specification, it is stored as a file in xml format and it should be committed to the project repository. Teamscale will use this architecture description to perform an automated architecture conformance analysis.

Architecture conformance results

The following results are produced by the architecture conformance analysis:

  • Actual types matching each component.
  • Types not matching any component, i.e., architecture orphans.
  • Actual dependencies corresponding to each defined policy.
  • Dependencies that were not defined in the architecture specification, i.e., violated policies.

The screenshot below shows the Architecture view in «assessment mode»: green arrows correspond to allowed policies, red arrows correspond to violated policies and the bottom of the screen shows a number of orphans or unmatched files.


Integration in development cycle

The architectural conformance findings that require attention are architecture orphans and violated policies. Resolution methods vary. For architecture orphans the resolution may be either correcting the namespace in which a type is defined or adding the orphaned types to a separate component and defining policies for that component. For violated policies, the resolution ranges from moving some code to a different component to reimplementing the functionality without using features of a denied-access component.

In any case, the resolution methods require collaboration between architects and developers and the new architecture editor feature of Teamscale makes it easy to integrate this process in the development cycle. After each commit that changes either the source code or the architecture specification, Teamscale provides feedback in real-time, within seconds after each commit regarding architectural conformance findings.

For architecture conformance analysis you can use an evaluation version of Teamscale that can be downloaded from here. What are your experiences with architecture conformance? Let me know in the comments.

  1. An article from Java Magazin describing different methods for evaluation of software architecture. Stefan Toth, Gernot Starke und Phillip Ghadir: Gut genug? Softwarearchitekturen bewerten. In Java Magazin, March 2015.

  2. An article describing a method for architecture conformance assessment as implemented within the ConQAT framework. Florian Deissenboeck, Lars Heinemann, Benjamin Hummel, Elmar Juergens: Flexible Architecture Conformance Assessment with ConQAT. In ICSE 2010.

  3. An article listing concepts used by different architecture conformance tools. Jo Van Eyck, Nelis Boucke, Alexander Helleboogh, Tom Holvoet: Using Code Analysis Tools for Architectural Conformance Checking. In Shark Workshop 2011.