Sonar recently released new functionality in SonarQube that allows you and your team to formally define and automatically verify your architecture. Read on!
What’s the problem?
Software systems are complex.
When new developers join a project, they turn to documentation or rely on experienced colleagues sketching a high-level diagram for them. Teams sometimes go a step further and use diagramming tools like Miro, Lucid, Mermaid, PlantUML, etc, to visualize how their system is composed as part of their documentation. While helpful, these informal descriptions are rarely accurate.
Over time, inconsistencies between the intended design and actual implementation accumulate. This mismatch makes it harder to plan work without unexpected surprises. A seemingly simple change can have unforeseen consequences because the system’s interdependencies weren’t fully understood. The result is delays, mounting delivery pressure, and teams taking shortcuts that lead to accidental complexity, making future development harder.
Even for experienced developers, understanding an entire codebase becomes impossible once it surpasses a few hundred thousand lines of code. And since codebases grow and change constantly, even a well-formed mental model quickly erodes with every new commit.
Such mental models, how you conceptualize the system’s structure, is effectively software architecture. And in most teams, architecture documentation drifts out of sync with reality. Over time, the gap between intended design and actual implementation widens, a phenomenon known as architecture erosion.
Keeping code in sync with your mental model
Several tools exist to help prevent architectural erosion and decay by formally defining architectural rules and continuously verifying that the code aligns with them.
Take ArchUnit, for example. It provides a clever approach where you write tests for your architecture and run them in your pipeline to ensure your design remains intact. This is better than nothing, but you'll quickly run into limitations.
Here are some of the trade-offs:
- Language-specific. If your stack includes multiple languages, you’ll need separate tools for each, adding learning, setup, and maintenance overhead.
- Rules aren’t the same as a model. A collection of rules doesn’t provide a high-level architectural view. Unlike a whiteboard diagram, which instantly conveys structure, rule-based approaches require reading test code to reconstruct the intended design.
Also, advanced commercial tools exist, but they often have a high learning curve and expensive per-seat licensing, making them difficult to scale for everyday use across multiple teams.
How Sonar Helps
To provide a more accessible and scalable solution, we are introducing Architecture as Code in SonarQube. A language-independent, declarative approach that allows teams to define architecture, store it alongside their code, and automatically verify it during CI/CD analysis.
With Sonar’s Architecture as code, you can now:
- Define your architecture as code in a YAML or JSON file, as a declarative model
- Automatically analyze code structure during Sonar’s static analysis process, no changes to the source code, or additional setup required
- Sonar raises issues when there is any architecture divergence between your model and the code
- Model multiple perspectives of your system, allowing different views based on your needs (e.g., layers, features, or domain boundaries)
Architecture as Code
Verification
This allows you to continuously verify architectural constraints during CI/CD, ensuring that code changes align with your defined model and detecting erosion before it becomes a problem. Any architectural deviations are raised as issues against the source lines that cause them.
Architecture as Code is available in SonarQube Server starting in version 2025 Release 2. SonarQube Server currently supports architectural drift in Java code. Detecting architectural drift in Java, JavaScript, and TypeScript is currently supported in SonarQube Cloud. Python and C# are coming soon. C++ is under consideration. You can send your request for other languages.
Defining Architecture: A Practical Example
A common way to structure an application is by using layered architecture, where different layers such as API, business logic, and data access should remain isolated. In Sonar, you can define this structure using Perspectives and Constraints.
Defining a perspective for layers
This configuration example below ensures that architectural layers remain independent, preventing unintended dependencies.
Notice that you can add a custom message that developers will see when Sonar raises an issue if an architecture divergence is found. Also, use of wildcards lets you ensure a consistent structure across your codebase.
perspectives:
- label: "Layers"
description: "Defines application layers and enforces separation of concerns."
groups:
- label: "API"
patterns: ["**/api/**"]
- label: "Business Logic"
patterns: ["**/service/**"]
- label: "Data Access"
patterns: ["**/repository/**"]
constraints:
- from: ["Business Logic"]
to: ["API"]
relation: deny
message: "Business logic should not depend on API layer."
- from: ["Data Access"]
to: ["Business Logic"]
relation: deny
message: "Data access should not depend on business logic."Adding a Perspective for features
In addition to layers, teams often organize code by features. A separate perspective can help visualize and enforce these structures.
perspectives:
- label: "Features"
description: "Defines feature-based boundaries."
groups:
- label: "User Management"
patterns: ["**/features/user/**"]
- label: "Payments"
patterns: ["**/features/payments/**"]
constraints:
- from: ["User Management"]
to: ["Payments"]
relation: deny
message: "User management should not depend on payments."By defining multiple perspectives, teams gain flexibility in how they model and enforce architecture, allowing for both technical structure (layers) and business structure (features) to be tracked in parallel. Really, any way you want to model your domain is possible.
This enables your team to describe the system in their own terms, while Sonar does the hard work of checking nothing is going off track.
Start using Architecture as Code today in SonarQube. Check out the documentation to get started.
Coming Soon: Interactive Visualization
Defining architecture as code is great, and what if you could see a visual representation of your architecture?
We’re working on an architecture visualization feature in SonarQube, eliminating the need for manually drawn diagrams that quickly become outdated.
Soon, you’ll be able to visually explore your code structure through your defined perspectives, interact with architectural elements, and ensure your code aligns with your intended design, all in one place. In SonarQube, the same architecture as code format will be used for defining your architecture, verifying it, and visualizing it. Share your thoughts about this upcoming feature.
Stay tuned for more updates!
If you're not already using SonarQube Cloud or SonarQube Server, get started. If you're on an older version of SonarQube Server, upgrade to the latest version so you can start using the new design & architecture capability.