> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/architecture-analysis/project-architecture.md).

# Project architecture

Visualize the current architecture of a project, define the architecture you intend, and fix the architecture problems that analysis raises.

Every analyzed project gets a map of its current architecture, an editor for the architecture you intend, and a list of the problems between the two. Everything on this page is scoped to a single project. To see how your projects connect to each other and to the rest of your system, see [Enterprise architecture](/sonarqube-server/architecture-analysis/enterprise-architecture.md).

The Sonar Architecture features for a project are located in the **Architecture** section of the navigation of the SonarQube Server UI.

## How to use Sonar Architecture

The process is driven by the tech leads who:

1. Understand the [current architecture](/sonarqube-server/architecture-analysis.md#current-architecture).
2. Define the [intended architecture](/sonarqube-server/architecture-analysis.md#intended-architecture) to constrain the most important structure and relationships, by starting at the top-level and working down into the structure. The intended architecture will be compared to the current architecture to raise deviations during analysis.
3. Review flaws in the current structure automatically identified by SonarQube, and make suggestions for repairs.
4. Iteratively evolve and extend the intended architecture as the code and priorities change.

As a developer, your role is to:

1. Fix the [SonarQube issues](/sonarqube-server/user-guide/issues/introduction.md) that are raised by SonarQube following tech lead input.
2. Explore the evolving intended architecture to ensure compliance as you add or modify code, and when addressing raised SonarQube issues.
3. Explore the current architecture to refresh your understanding of the project topology, and to gain insights for specific tasks.

## Viewing the current architecture

SonarQube Server provides an interactive visual map to explore the structure and relationships within your codebase.

The map allows you to:

* Understand the current topology of the project.
* Navigate to understand the map in more or less detail.
* Focus on the relationships of a specific container.

There is no special setup or input needed to view and use the map. It is automatically updated after each analysis so it is always up to date.

**How to read the map**

To access the current architecture map, go to **Architecture** > **Current architecture**.

Classes/files are recursively grouped within their packages/folders/modules. The size of containers generally reflects the number of underlying containers, but the white space inside a container also characterizes it.

In every container (also true for top level containers), sub-containers are levelized, which means they are organized as follows:

* Containers that have no outgoing relationships are located on the right.
* Every container in a column has at least one dependency on the next column on the right.
* Containers in a column have no dependencies between themselves.

This means that relationships will generally flow from left to right. This conveys the flow of relationships without showing all the specific relationships.

To display direct relationships to/from selected containers, click on the container.

**How to use the map**

To explore the map, pan, zoom, and click:

* Zoom to see more or less detail.
* Select any item at any level to see its relationships.
* Pan across the map or zoom out to see regions or relationships that are off-screen.

## Creating an intended architecture

You can create and update a visual model that expresses the intended structure and relationships within your codebase. This intended architecture will serve as the reference: during analysis, deviation issues are raised when the intended architecture and current architecture don't match.

The intended architecture editor lets you:

* Formalize the structure and relationships in a way that is straightforward and incremental: you can stop at any point in time.
* Decide which containers should be inspected, as SonarQube inspects them only once they are added to the intended architecture.
* Define a structure using a top-down approach.

Note that to create the intended architecture, you only define allowed relationships between sibling containers. Relationships are inherited by sub-containers.

All the above tasks require the **Administer architecture** permission, which project administrators have by default.

Instead of defining a structure from scratch, you can reuse a model your organization has already agreed on. See [Enterprise architecture](/sonarqube-server/architecture-analysis/enterprise-architecture.md#defining-architecture-patterns).

## How to use the intended architecture editor

To access the intended architecture editor, go to **Architecture** > **Intended architecture**.

Your goal is to define the structure and relationships in your code.

* Structure: Which containers you care about, and where they should be located.
* Relationships: How should the containers in the model depend on any of their peers in the model.

Starting at the top-level of your structure, add the containers and sub-containers that you most care about.

Every time you add a container to the model, you should immediately define the allowed relationships to its siblings to keep the model complete. Indeed, any non-defined dependency between siblings will be considered as forbidden.

You can follow your progress by looking at the list on the right. Every time you add a container to the map, the corresponding containers in the list are removed.

You can stop at any time, and start again. You should expect to regularly modify the intended architecture as the codebase evolves.

{% hint style="success" %}
Remember to click **Save** so that your updated model is picked up and used by the next analysis.
{% endhint %}

## Architecture problems

Architecture problems in the current architecture are detected automatically during the project analysis.

### Understanding architecture problems

Architecture problems fall into three categories:

* **Flaws** are structural problems that exist in the codebase regardless of the intended architecture. Flaws include tangles and oversized components.
* **Smells** are architecture problems that tend to worsen over time, increasing coupling and making changes harder to localize. Smells include weak tangles and split responsibilities.
* **Deviations** are differences between the current architecture and the intended architecture. They are raised only when you have defined an intended architecture, and they raise [SonarQube issues](/sonarqube-server/user-guide/issues/introduction.md). SonarQube detects two types of deviations: wrong dependencies and wrong locations.

For each type of SonarQube issue, you get a list of issues, ordered by priority. For tangles, you get a visual representation of the problem and can instruct developers how to solve it.

### Fixing architecture problems

When you review the list of architecture problems:

* For deviations, make sure that they are in line with your intention.
* For flaws such as tangles, pick the ones you wish to solve and review them. Select the undesirable relationships to create a directive, an instruction that guides how developers fix the flaw. The next analysis raises SonarQube issues when these relationships are detected.

## Related pages

* [Architecture analysis](/sonarqube-server/architecture-analysis.md)
* [Enterprise architecture](/sonarqube-server/architecture-analysis/enterprise-architecture.md)
* [Introduction](/sonarqube-server/user-guide/issues/introduction.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/architecture-analysis/project-architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.