Design and Architecture overview

Design and Architecture is available in the all commercial editions of SonarQube Server. It is currently supported on Java. You can send your request for other languages.

With Sonar’s architecture as code approach, you can formalize your architecture and store it under version control alongside your code. 

Sonar automatically verifies that your code aligns with your architecture during CI/CD and raises issues when it detects divergences. This allows you to detect design drift before it causes structural erosion or adjust your architecture as needed.

This workflow ensures that architecture remains a first-class concern throughout development. Your team can enforce design decisions consistently, developers can refine the codebase structure, and all stakeholders can make informed decisions based on accurate architectural insights.

Why architecture matters

Architecture provides a high-level understanding of your system, helping your team make informed decisions and stay aligned on how the system works and evolves.

But code naturally drifts from its design. Small changes accumulate, boundaries erode, and dependencies grow uncontrolled. Each team member forms a slightly different mental model, making collaboration harder. This gap between perception and reality increases risk. Uncertainty slows development and makes changes costly.

By defining architecture formally and keeping it in sync with code, you ensure everyone has an accurate understanding. This lets your team confidently build, evolve, and sustain your software over time.

Architecture definition

Define your architecture 

Define your architecture as code, formally and declaratively, via a YAML or JSON file. This enables versioning alongside your code and allows for automatic enforcement.

You can specify system elements and constraints with just a few lines of configuration or define perspectives, hierarchical structures that reflect your problem domain. Perspectives provide flexibility in modeling your architecture and how it maps to your code. See the Configuring the architecture analysis page for more information.

Code structure analysis

Sonar analyzes your code structure without requiring additional configuration. This happens automatically as part of its existing static analysis process, meaning if you’re already running Sonar, you're all set.

During this step, Sonar extracts essential code facts, such as all defined classes, modules, and their inter-dependencies. This serves as the ground truth of your codebase, forming the foundation for architectural validation.

Matching code and architecture 

Sonar compares your actual code structure against your architecture model, ensuring they stay in sync. If divergences occur, Sonar raises issues, helping you identify and repair misalignments.

See the architecture verification section for more details.

Architecture verification

Code structure analysis

During CI/CD analysis, Sonar re-extracts code facts to ensure verification is based on the latest state of the codebase.

Architectural constraints

You can define architectural constraints to enforce design rules, such as forbidden dependencies, layer boundaries, and granular structural rules. See the architecture file format in Configuring the architecture analysis page for details.

Identifying divergence

Sonar maps relationships between code elements, such as dependencies, onto your architecture model. This step establishes how the actual implementation aligns with your defined structure.

Sonar then compares the implementation with your architecture, identifying mismatches where the code diverges from the intended dependencies, boundaries, or structural rules.

Raising issues

When Sonar detects divergences, it raises issues referencing the specific constraint involved. These issues are raised during your CI/CD pipeline, helping developers quickly identify and resolve architectural drift before it becomes a larger problem.

Keep in mind that the architecture rules should be in your Quality Profile for architecture verification to work. Depending on the language, Sonar enables the rules by default in the Sonar Way profile.

Cycle detection

Sonar automatically detects and raises circular dependencies as issues in supported languages. No additional configuration is needed beyond ensuring that the rules are included in your Quality Profile.

See Cycle detection for more information.

Perspectives

A Perspective is a structured view of your codebase, defining how parts of your code are organized into architectural elements, called Groups. Groups can be nested, forming a hierarchy that reflects your domain concepts.

A project can have multiple Perspectives, each offering a different view of the architecture. For example, one Perspective might illustrate architectural layers, while another maps features to the relevant parts of the code.

Constraints

An architecture constraint is a rule your team defines and enforces through Sonar. Constraints are declared in the architecture file, and Sonar verifies them in CI/CD, raising issues when divergences occur.

There are two types of constraints:

• Group constraints: Defined within a Perspective and apply to the hierarchical groups it defines
• Top-Level constraints: Apply to the entire codebase and use raw code patterns like globs and wildcards