Architectural Decision Enforcement: From Architectural Decisions to Automated Conformance Checks

Architectural decisions play a central role in software architecture and
are often documented using Architectural Decision Records (ADRs). Managing
such decisions involves identifying architecturally significant choices,
documenting them as ADRs, and enforcing them as the codebase evolves. In
practice, enforcement is often the weakest phase and is usually left to costly
and inconsistent code reviews. Existing architecture conformance tools can
automate checks on code, but they are disconnected from the ADRs that
motivated their rules. This gap can lead to architectural erosion over time.
This thesis proposes to bridge the gap between decision documentation
and automated conformance checking with the Architectural Decision
Enforcement (ADE) tool. ADE introduces a tool-agnostic domain-specific
language (DSL) in which rule files, located alongside ADRs, express enforceable
constraints without knowledge of specific testing frameworks. To decouple
rule specification from execution, we developed a compiler architecture
consisting of a parser, semantic validation, and an intermediate representation
based on Protocol Buffers. This allows the same rule file to be used
with multiple enforcement frameworks. We further define a plugin protocol
that enables independently developed plugins to target different language
ecosystems.
The proposed approach supports architects in enforcing architectural
decisions throughout software evolution. We implemented a command-line
tool with reference plugins for Go, .NET, and filesystem assertions. Applying
ADE to an open-source .NET project containing 17 ADRs showed that 9
decisions could be automatically enforced, resulting in 44 generated checks.
As part of our action research, an architect applied ADE to a multi-language
project and developed an independent Java plugin. This demonstrated that
the plugin protocol can be applied to new ecosystems without changes to
the ADE core. The validation activities indicate that a tool-agnostic DSL
combined with a plugin-based execution model can effectively connect ADRs
with automated conformance checks, minimising architectural erosion.