As software architects, we all start with the best of intentions: clean structure, clear responsibilities, and those satisfying diagrams full of neat boxes and arrows. But then… real life happens.
Deadlines get tight. Features shift. A teammate’s out of office. Someone hardcodes a workaround to meet an important deadline. It works, but nobody updates the documentation. Just like that, your carefully designed architecture begins to erode.
This erosion doesn’t come with a bang: it creeps in silently, layer by layer, decision by decision.
In our recent talk at Qt World Summit, we asked a critical question:
How do you stop architectural erosion before it quietly derails your system?
Our experts at Axivion, Dr. Andreas Gaiser and Dr. Daniel Simon, have spent years helping teams bring architecture back into their day-to-day workflows as something actively enforced in code. In this post, they will walk you through the key ideas from the session, and how you can make architecture verification a practical reality.
It Starts with Boxes and Arrows… Then Reality Hits
We kicked off the session with a story you’ve probably lived through.
Imagine a textbook architecture for a small system implemented in C or C++: a neat three-layer design with hardware abstraction at the bottom, middleware in the middle, and a Qt-based UI on top. It’s all perfectly separated. Then reality knocks. A prototype is needed tomorrow for a trade fair. The middleware developer is out sick. So, someone connects the UI directly to the hardware.
No problem—“It’s just for the demo.”
But that zigzag workaround never makes it into the architecture diagram. Nobody updates the architecture specification. The gap between “what we meant” and “what’s in the code” widens. That’s how erosion begins. The worst part? It’s invisible. Until it isn’t.
Why Architecture Verification Is Essential
Architectural decay is not about bad code; It is about uncontrolled divergence between design and implementation. What we need is a way to see that divergence as it happens. That’s where static analysis comes in.
Think of it like placing your architecture model on a transparency sheet and laying it over your real code. If the connections don’t align, you know exactly where the issues are.
With static analysis and architecture verification, you can:
- Detect architecture violations and hidden dependencies
- Spot unused components and obsolete links
- Prevent long-term decay by enforcing architecture in CI
- Understand what’s really happening in your codebase
And importantly, this works without running your code. It’s all static.
A Practical Approach to Architecture as Code (AoC)
The boxes and arrows are a great tool for visualization (consider UML just as being a special variation of it). However, in large scale projects some architects prefer another scalable path forward: Architecture-as-Code.
Forget fragile diagrams and proprietary modeling tools. Instead, we write the architecture model as clean, human-readable Python code. Yes—code.
In this approach:
- Components become classes or declarations
- Dependencies are defined with clear, readable rules
- Access boundaries (e.g., public vs. private interfaces) are explicitly modeled
And the model lives with the codebase, versioned your version control, e.g. Git, can be edited in your IDE, and reviewed like any other file.
You don’t need to learn a new UML tool or manage XML-based models in isolation. The Python DSL makes architecture accessible and enforceable.
The Three Ingredients of Architecture Verification
To move from static diagrams to enforceable architecture, you need three key ingredients:
- Architecture Model – a structured definition of components and their allowed dependencies (e.g. via Python DSL)
- Code Model – generated from your source via static analysis
- Mapping – a link between code elements (files, directories, functions) and their architectural roles
Without all three, architecture checks are guesswork. With them, you get precise, actionable insight into violations, absences, and unexpected dependencies. Note that these three ingredients are not for the sake of verification – these are likewise required if you just want to “talk” with your developers.
This mapping step is often overlooked, but it’s what turns architecture into something enforceable. You can define mappings by file paths, directories, even individual classes or functions. And you can refine them to model internal vs. public access points.
What You Can Detect (and Fix) with Software Architecture Verification
Once your architecture model, code model, and mapping are defined, you can start enforcing rules automatically during development or in CI pipelines.
The system flags three main situations:
- Convergence: The code matches the architecture. All good.
- Divergence: The code violates an architectural boundary (e.g., UI calls hardware directly).
- Absence: The architecture defines a dependency that doesn’t exist in the code anymore.
Each case has different implications. Divergences need fixing, or at least a conversation. Absences might mean obsolete architecture or unused components.
In our session, we showed real examples: A global variable accessed through an internal header, functions bypassing middle layers, and dependencies creeping in silently. Every one of these was visible in the graph, and tied back to the source code, thanks to mapping.
Make Architecture a Living Part of Development
We believe architecture should be a living artifact, not a PowerPoint or a forgotten Confluence page. It should live in your repository. It should evolve with your team. And it should be verified continuously.
And you don’t have to model everything upfront. Start small, as even a basic high-level model will catch real violations, especially in legacy systems where nobody quite remembers what depends on what.
In this session, Dr. Daniel Simon and Dr. Andreas Gaiser walk through real-world examples of architecture verification using Axivion, showing exactly how to catch violations early, model architecture in code, and keep systems from quietly drifting off course.
How Axivion Makes It Real
Everything we showed, from the architecture DSL to code mapping, static analysis, and violation reports, is available out of the box in the Axivion Suite.
With Axivion, you get:
- A clean Python-based DSL for architecture modeling
- Automatic code-to-architecture mapping
- Static analysis that detects architectural violations, code clones, and erosion trends
- Deep integration into your IDE and CI/CD pipeline
- Visual tools to explore dependencies, review issues, and guide decisions
In short: you turn architecture into something visible, enforceable, and real every day.
See It In Action
In the full session, we walk through a real (and intentionally messy) project. You’ll see how even simple erosion, like a shortcut for a trade show demo, can cascade into deeper violations. And you’ll learn how to stop it before it grows.
Let’s stop pretending architecture lives in diagrams. Let’s make it live where it matters: in your codebase:
Watch the full talk here
Explore the Axivion Suite
