Architecture Conformance

How Architecture Conformance Is Examined

An architectural description can do more than show which components a system has.
It can also contain specifications for how these components should relate to one another.

Examples include:

• permitted and prohibited dependencies
• defined layers
• intended interfaces
• permitted communication paths
• technologies that may be used
• security boundaries
• responsibilities of individual components
• rules for data access

An Architecture Conformance check compares such specifications with the actual system.

In simplified form:

Architectural specification
        ↓
testable rule
        ↓
actual system state
        ↓
comparison
        ↓
conformance or deviation

The difficulty often already lies in turning an architectural decision into a sufficiently concrete, testable rule.

Documented and Actual Architecture

The documented architecture of a system and its actual architecture do not necessarily remain consistent over time.

For example, a document can specify:

Web applications access customer data exclusively through the API service.

Later, a developer needs additional data at short notice and adds direct database access.
The system continues to work.
The documentation has not been changed.

There are now two different states:

documented architecture:
Web → API → database

actual architecture:
Web → API → database
  └────────→ database

Without a corresponding examination, this deviation can remain unnoticed for a long time.

Architectural Rules Must Become Testable

Statements such as:

Our software should be modular.

are understandable as architectural principles, but can only be tested automatically to a limited extent.

A more concrete rule could be:

Components of module A must not directly access internal components of module B.

Or:

Database access may occur exclusively from the persistence layer.

The more precisely an architectural rule can be described, the easier it is to examine whether the actual system conforms to it.
Not every architectural decision can be translated completely into an automatable rule.
Some decisions still require human assessment.

Different Types of Examination

Architecture Conformance can be examined in different ways.

Reviews

People examine source code, architectural models, or changes and compare them with existing architectural decisions.
This makes it possible to assess complex relationships, but it is time-consuming and can overlook relevant deviations.

Static Analysis

Source code and dependencies are examined without executing the system.
This can, for example, identify prohibited module dependencies, layer violations, or certain libraries being used.

Automated Tests

Architectural rules can be formulated as tests.
A build can, for example, fail if a component accesses a prohibited layer.

Runtime Analysis

Not every relevant architectural relationship can be identified completely from the source code.
Dynamic communication paths, external services, or deployment structures can additionally be examined in the running system.
The appropriate method depends on which architectural rule is to be checked.

Conformance Is Not the Same as Quality

A system can fully conform to its architecture and still be poorly designed.
If the architecture explicitly specifies an unnecessarily complicated dependency, an implementation of that dependency is architecturally conformant.

The conformance check initially answers only:

“Does the actual system conform to the defined specification?”

It does not automatically answer:

“Is this specification sensible?”

These are two different questions.

A Deviation Does Not Automatically Require a Correction

If an architectural rule is violated, there is a deviation between the expected and actual state.
This does not automatically mean that the implementation must be reverted.

Possible causes include:

• unintentional violation of a rule
• lack of knowledge about the architecture
• short-term technical workaround
• changed requirements
• incomplete architectural specifications
• an architectural decision that has since become unsuitable

The appropriate response can therefore differ.
The implementation can be corrected.
The deviation can be consciously accepted and documented.
Or the architecture itself must be changed.

The conformance check initially provides the information:

“The target and actual states differ here.”

Architecture Drift

If more and more deviations between the documented and actual architecture accumulate over a longer period, this can be referred to as architecture drift.
A single deviation does not necessarily represent a major problem.
However, many unknown deviations can cause architectural models and documentation to lose their evidentiary value.
This becomes relevant at the latest when a system is to be changed, integrated, or modernized.
A supposedly simple change can suddenly affect unexpected dependencies that do not appear anywhere in the known architecture.
Regular conformance checks can make such developments visible earlier.

Rules Can Become Machine-Readable

Some architectural rules can be formulated so that tools can check them automatically.

For example:

Rule:
Module frontend must not import module database.

A tool can then examine the actual dependencies:

frontend → api       permitted
api      → database  permitted
frontend → database  VIOLATION

This turns compliance with an architectural decision into a repeatedly testable property of the system.
The architecture then no longer exists exclusively as a diagram or document.
Some of its rules can be checked directly against the actual system.

Automatic Enforcement Is a Separate Decision

An identified deviation can have different consequences.

A tool could:

only log it

or:

generate a warning

or:

require a review

or:

abort the build

Checking a rule and enforcing it are therefore two different decisions.
This is particularly important for rules whose violation does not have the same significance in every context.
An automatic check does not necessarily have to trigger an automatic correction or block.

AI-Generated Code Does Not Change the Problem

If source code is generated by an AI system, the same architectural rules apply as for human-written code.

A model can receive a specification in its context:

All output must go through the central logging component.

Nevertheless, it can generate code that writes directly to standard output.

This creates two different questions:

Did the model receive the architectural rule as context?

and:

Does the generated code actually conform to the architectural rule?

The first question concerns Context Engineering, among other things.
The second concerns Architecture Conformance.
Having a rule in the context is therefore not the same as demonstrating compliance with it.

Why Architecture Conformance Has Practical Effects

• Architecture drift becomes visible: The documented and actual system can be compared with one another.
• Architectural decisions become testable: Concrete rules can emerge from principles.
• Dependencies remain more controllable: Prohibited connections can be identified early.
• Reviews can be supported: Automatable rules do not have to be searched for manually again with every change.
• Legacy systems become easier to examine: Actual dependencies can be compared with existing documentation.
• AI-generated code can be subject to the same rules: The origin of the code does not change the architectural specifications.
• Deviations are initially made visible: Examination and response remain separate steps.

Typical Example

A software project has a central component for command-line output.

The architectural rule is:

Application components do not generate direct output on stdout.
All output goes through the designated component.

During a change, new code is created:

print("Operation completed")

The function works correctly from a technical perspective.
However, it violates the defined architectural rule.
An automated conformance check identifies the direct output call and reports the deviation.

A decision must now be made:

Is the implementation wrong?

or:

Is there a good reason for this exception?

or even:

Is our existing architectural rule unsuitable for this case?

The check does not answer these questions automatically.
It initially ensures that they can be asked at all.

Distinction

• Architecture Conformance describes the conformance of the actual system with defined architectural specifications.
• System Architecture describes the fundamental structure of the system, its elements, relationships, interfaces, and architectural principles.
• Verification and Validation consider more generally whether requirements are met and whether a system is suitable for its intended purpose. Architecture Conformance can be a subject of verification.
• Observability enables conclusions to be drawn about the actual states and behavior of a system. Such information can be used for conformance checks.
• Policy as Code takes a step toward machine-readable rules. Architectural rules can be formulated as such policies and checked or enforced automatically.

Further Reading

Related Concepts

→ System Architecture
→ Systems Analysis
→ Verification and Validation
→ Observability
→ Context Engineering
→ Policy as Code
→ Resilience