# Architecture Perspective
In the Architecture perspective, you can model and analyze the architecture of your system.
Teamscale provides an architecture conformance analysis to check if the implementation follows the architecture specifications.
Therefore, the architecture specifications (.architecture-files) can be modeled using nested components.
The specifications can then be committed to the version control system or saved in Teamscale itself to be used for continuous conformance checking.
For an high-level introduction to architecture analysis, check out our blog post on Challenges of Architecture Documentation (opens new window). Or have a look at our short guide on how architecture conformance analysis works in Teamscale (opens new window).
Language Support
Architecture Analysis is currently supported for
- ABAP / ABAP Dictionary
- C/C++
- C#
- HANA View
- IEC61131
- Java
- JavaScript / TypeScript (ES6, Google Closure, Typescript Modules)
- Kotlin
- Matlab
- PHP
- Python
- Simulink
# Prerequisites for Architecture Analysis
To enable the architecture analysis, the architecture quality indicator has to be enabled in the analysis profile of the underlying Teamscale project.
Enabled in Default Profiles
Architecture analysis is enabled in the default analysis profiles that come with Teamscale.
In the analysis profile, you can also configure if third-party dependencies should be considered in the architecture analysis or excluded from it:
# Architecture Overview View
When you open the Architecture perspective, you will see an overview of existing architecture specifications:
This overview will be empty initially if no architecture has been modeled yet. For each existing architecture model, the table shows its status and the available options.
The following states are possible:
| stored in repository | Indicates that the architecture file is stored in the version control system. Modifications to this architecture are saved by downloading the architecture file and committing it to the repository. If this sign is absent, the architecture file is stored on the Teamscale server. |
| analysis complete | Indicates that the analysis of the architecture file is completed. |
| recently added - analysis running | Indicates that the analysis of the architecture file is still running. Hence, the architecture cannot be viewed yet. |
| recently deleted - analysis running | Indicates that an architecture file has been deleted and that the analysis is still running. |
The following actions are available:
| Shows the metrics for the code modelled in the given architecture, similar as in the Metrics perspective. | |
| Deletes the architecture. This is only an available if the architecture is stored in Teamscale. Architectures stored in the repository can be deleted only by deleting them from the repository |
# Teamscale's Architecture Model
The intended architecture can be specified in a simple yet powerful hierarchical component model. The model has few basic concepts:
Components: The system is modeled as a hierarchy of components. A component has a unique name and mappings and may have subcomponents. Components can have a stereotype
PUBLICindicating that all other components may access this components or a stereotypeCOMPONENT_PUBLICspecifying that it may be accessed by all other components within the same parent component (e.g., a GUI-library within an UI-layer). This is especially useful for library components that are accessed by many other components.Mappings: A mapping between code and architecture defines which implementation artifacts belong to which component in the architecture definition. This is specified using Java regular expressions as include and exclude pattern.
Architecture Type: For an architecture, you can choose if the architecture is type- or file-based. For a type-based architecture the full-qualified names of all types (classes, structs, enums, etc.) in the code base are used for the mapping. For file-based architectures the path to the source code files are used.
Policies: A policy defines which components may be in a relationship (allow, deny, tolerate) with each other. Each dependency policy has a source and a target component. If components are not connected by a policy-edge, dependencies between them are (implicitly) forbidden. You need to explicitly model allow-policies (green arrows) to allow dependencies. If an allow-policy is specified between two components all of their sub-components may also share dependencies. You can explicitly deny this, by modeling deny-policies (red arrows). Toleratepolicies can be used to accept an explicit set of dependencies between components.
Violations: If additional dependencies are introduced, which contradict the modeled policies, Teamscale will mark them as violations of the architecture. Violations can be defined to be treated as regular findings in Teamscale. This can be configured while editing the architecture.
Orphans : Types/files that reside within the scope of the architecture, but are not mapped to a component, are regarded as so-called orphans. These orphans can be defined to be findings in Teamscale. This is to be configured while editing the architecture.
 | The code adheres to the specified allow or deny policy. This means dependencies have been identified in case of an allow dependency or no dependencies are present in case of a deny policy. |
 | The code violates the specified allow or deny policy. This means an architecture violation has been identified. Dependencies have been identified, but no allow policy is modeled between the dependent components. |
 | The policy is unnecessary. An allow-policy is specified, but no dependencies have been found. |
# Action: Model Architecture
After having gained a basic
understanding of the Teamscale architecture model in the previous
section, we can now start to model our own architecture specification.
When you open the Architecture perspective and click on New Architecture, the Architecture Edit View opens. (You will reach the same view upon
opening an existing architecture and clicking on Edit Architecture.)
# Architecture Edit View
When creating a new architecture, the editor will be empty. Underneath, a variety of options are displayed on the left and the current orphans are displayed on the right.
On the left side, you can edit the name of your architecture specification file and choose, whether the architecture should be based on file dependencies or type dependencies (see our architecture model). You can also configure, whether findings should be created for both violations and orphans, or just for violations, or for neither one. Furthermore, the scope of the architecture can be defined. By default, the scope of the architecture matches the scope of the underlying project. It can be narrowed down by defining explicit include or exclude patterns, e.g., to exclude test code.
Additionally, constraints can be configured. A constraint represents a
deny policy based on regular expression patterns. For example, in a
file-based architecture definition, you may want to add the constraint
$.*/src/.* -> .*/test-src/.*$ to indicate that source code
should not depend on test code. In the simplest version, if the regex
matches exactly two components, the constraint leads to an identical
result as an explicitly defined deny policy between these two
components. However, there may be cases, in which policies cannot be
matched directly onto components (or it would create overload in
creating the specification). Hence, it might be easier to define
additional constraints orthogonal to the component definition.
On the right side underneath the editor, the orphans are shown. If no architecture has been created yet, all files or types will be considered orphans.
# File-based vs Type-based Dependencies
In architectures based on file dependencies, orphans are displayed based on the folder structure of the project.
For architectures based on type dependencies, in contrast, they are displayed type-based, e.g., according to their package structure for Java.
# Modelling your architecture
To start modeling the architecture, the sidebar of the Architecture Edit View provides you with the necessary tools:
 | Create a new allow policy |
 | Create a new deny policy |
 | Create a new tolerate policy. This will cause findings for newly added dependencies between the components. |
 | Create a new component |
 | Show/hide all policies |
 | Show/hide allow policies |
 | Show/hide tolerate policies |
 | Show/hide deny policies |
 | Show/hide policies to which the code is conform. Works only when the checkbox Display assessment is marked. |
| Show/hide policies which are violated by the code. Works only when the checkbox Display assessment is marked. |
 | Show/hide unnecessary policies (e.g., allowed dependencies that are not present in the code). Works only when the checkbox Display assessment is marked. |
Usually, you start by
creating the first component(s). Click on
and then hover over the white (currently still empty) editor field to
drag & drop your first component. As show here, you can give each
component a name:
Alternatively, from the orphans at buttom-right, you can drag & drop folders or packages onto the editor. A new component will be created for every item dropped while mappings and dependency policies will automatically be created. Within the editor, components can be dragged into or out of other components and this will adjust the mappings and dependencies accordingly. If the checkboxes display assessment and update automatically in the right sidebar are marked, you will see how many types are matched to the component. You can also manually trigger the update of the assessment by clicking the Update Assessment button. This works if Auto-Update is unchecked.
Each component has a number of properties that are presented for modification when clicked. The properties are shown in a panel with resizable height below the editor. In this example, the name of a component as well as some descriptive comment can be changed:
If a component has
dependencies, they are by default visible as arrows in the editor. Their
visibility can be controlled under Policies Visibility by clicking the
Hide All and Show All toggle buttons for the Outgoing and Incoming
dependencies. The Stereotype of a component indicates whether it can
be accessed by all components (reflected in the value PUBLIC) or just by
only components within the same parent component (value
COMPONENT_PUBLIC). Mappings can be added, deleted or modified.
With the buttons in the sidebar on the right, you can model policies between components:
For example, click on
to create an allow policy and then first click on the source component
and - while keeping the mouse button clicked - drag the upcoming
policy arrow till you hover over the target component. Then release the
mouse button and a green policy should appear:
Similarly, you can create tolerate
and deny
policies.
While you are modeling your architecture, Teamscale will assess the created policies on the fly, if the checkboxes display assessment and update automatically in the right sidebar are marked. Teamscale assesses whether the created policies are violated by dependencies in the source code.
This example shows, for example, that a modeled deny policy was, in fact, violated in the code by one dependency. Teamscale also displays source and target of the dependency and allows you to directly jump to the code file by clicking on the respective location link:
# Action: Save Architecture
When you are done creating your architecture, you need to save your changes. When you are in the Architecture Edit View, you can either download the architecture file to check it into your repository or you can save the architecture on the Teamscale server. Use the corresponding buttons in the sidebar Download Architecture or Save Architecture . In both cases, the change to the architecture file will show up as a commit in the Activity perspective. When you are storing the architecture in your repository, your regular commit to the repository will be displayed. When storing the architecture in Teamscale, an artificial commit will be created. The artificial commit is named »Changed architecture« and also has an artificial revision number:
When saving an architecture on the Teamscale server, it will be visible for all users of the underlying project - same as if you would commit it to the repository. Other users can not only read but also modify your architecture.
# Action: View Architecture
Often, you want to simply view an existing architecture, which was maybe created by your colleagues or by yourself several days ago. When you open the Architecture perspective and you already modeled an architecture, you can click on its name in the table of the Architecture Overview View. This will open the architecture in the Architecture Inspect View. A completely modeled architecture may look similar to this one:
# Architecture Inspect View
In this view, you can use the [Hide/Show] buttons in the sidebar to filter the policies in your architecture view.
You can also click on the components to inspect
which types were matched or click on the violations to see where they
are coming from. Additionally, you can download the architecture either
as XML file (Download Architecture) or as SVG file (Download as Image).
# Action: Inspect Metrics for Architecture
As Teamscale measures a variety of metrics for your system, you can also view them with respect to your architecture. When you open the Architecture perspective with the Architecture Overview View, you can use the Metrics button to inspect the metrics. This will provide you a view with a table, in which the metrics are aggregated based on the components of your architecture:
This table is the same as you can also find in the Metrics perspective. When you drill into it, you can navigate the various components and descend into sub-components till you reach a mapped code file. Along the way, the metrics in the table are always aggregated to the (sub-) component in which you are currently located. Hence, you can inspect, for example how large a component is in terms on lines of code, if a specific component is missing documentation or whether the test coverage varies greatly between different components.
In addition to the Architecture perspective itself, you can use your architecture specification also in other perspectives. For example, the Dashboard perspective offers to configure a widget for a specific (sub-) folder of your system. In analogy, a widget can also be configured for a (sub-) component of your system.
Architectures as Paths
Generally speaking, whenever you can choose a folder path from your project in Teamscale, you can also choose an architecture/architectural component instead.
# Webinar:
Webinar on Architecture Analysis (German)
- 01:27: Motivation und Grundlagen
- 08:45: Beispielsystem JabRef
- 11:27: Live-Demo Architektur-Rekonstruktion
- 25:07: Live-Demo Architektur-Konformanz
- 38:53: Live-Demo Architekturen als Sichten
- 49:05: Fragen der Teilnehmer