Enterprise architecture

See how your projects connect to each other and to the rest of your system, and enforce the same architecture decisions across many projects at once.

Enterprise architecture is in open beta. An administrator enables it in the organization settings. For more information on release stages, see Product release lifecycle.

Enterprise architecture is available in the Enterprise plan.

Enterprise architecture builds a map of the relationships across your SonarQube projects. The analysis finds the places where each project calls out of itself and the places where it accepts incoming calls, matches them, and draws the result across every project in your organization.

With enterprise architecture, you can:

• See how your projects connect to each other, and to the databases, queues, and third-party applications that SonarQube does not analyze.
• Define an architecture decision once as a pattern and apply it to every project that adopts it, instead of defining it project by project.
• Get deviations from those decisions as SonarQube issues, in the workflow your developers already use.

Patterns, SDKs, and system components are defined once for the whole organization, and need the Administer architecture permission. Mapping exit points is done project by project, by anyone with that permission on the project.

Prerequisites

• An organization on the Enterprise plan.
• An organization administrator has enabled enterprise architecture in Administration > Organization settings (open beta).
• Each project you want to see on the map has been analyzed.

How SonarQube detects relationships between projects

SonarQube ships with an internal catalog of code signatures covering built-in APIs and the most common frameworks, in each supported language: C#, Java, JavaScript, Python, and TypeScript. Analysis uses the catalog to find two kinds of location in your code:

• An exit point is a place where a project calls out of itself, such as an HTTP request, a SQL statement, a message published to a queue, or a process it starts.
• An entry point is a place where a project accepts an incoming call, such as a route it serves or a connection it exposes.

Analysis records the parameters and values at each location. A relationship between two projects appears when an exit point in one project matches an entry point in another. Exact matches are mapped automatically, with no input from you.

You can extend what SonarQube can detect:

• An exit point with no matching entry point, because the values differ or the target is not analyzed, can be mapped by hand. See Mapping exit points manually.
• A target that is not a SonarQube project at all, such as a database or a queue, can be represented as a system component. See Defining system components.
• A call that goes through an internal library or an unsupported framework can be detected by defining an SDK. See Extending detection with SDKs.

Viewing the cross-project architecture

To open the map, go to your organization and select Enterprise architecture > Current architecture. The map shows the projects analyzed by SonarQube and the relationships detected between them, and is rebuilt as projects are analyzed.

Nodes are grouped into bands, from top to bottom:

1. Projects with relationships.
2. Projects with unmatched entry or exit points.
3. System components without relationships.
4. Projects without relationships.

Reading the map:

• A warning triangle on a project means the project has exit points that could not be matched automatically. Open that project's exit points page to map them.
• A number on an arrow is the count of relationships that the arrow represents.
• Projects with nothing detected are collapsed into one card that tells you how many there are.

A project sitting in the second band is the signal to act on. It means SonarQube found the code that leaves the project but could not tell what it reaches.

Mapping exit points manually

Automatic mapping fires only on an exact match between an exit point and an entry point. When a URL is built at runtime, when two teams spell the same queue differently, or when the target is not a project SonarQube analyzes, the exit point stays unmatched until you map it.

To map an exit point:

1

Open the project's exit points

Go to your project > Architecture > Exit points. Each row shows the exit point that analysis found at that location.

2

Choose the target component

Under Target, select the component the exit point reaches. This can be another project or a system component.

3

Choose the entry point

Select an entry point within that component. Components with a single entry point offer default.

4

Save

Click Save. The relationship appears on the cross-project map, and the warning triangle clears once every exit point in the project is mapped.

Rows that analysis matched on its own carry an Auto-mapped badge and cannot be edited.

Defining system components

Not everything your projects talk to is a project that SonarQube analyzes. A system component stands in for one of those: a database, a message queue, or an external application such as a payment provider.

To create one, go to Enterprise architecture > System components, click Create system component, enter a Name, and choose a Type of Application, Database, Queue, or Other.

A system component then appears on the cross-project map and becomes selectable as the target of an exit point. Name it the way your teams already refer to it, because that name is what everyone reading the map will see.

Extending detection with SDKs

The built-in catalog covers common APIs and frameworks. It does not cover the internal client library your platform team wrote, or a framework that SonarQube does not support yet. An SDK tells analysis what that code looks like and which component it reaches.

To create one, go to Enterprise architecture > SDKs and click Create SDK. Provide:

• Name: how the SDK appears in the list.
• Target component: the project or system component that the code reaches.
• Detection signature: the Language to search, and the Code signature to look for, such as java.net.http.HttpClient#send(**)** or com.example.Manual.*.

The next analysis of a project uses every SDK defined for the organization, so a single definition covers every project that calls that library. When the code signature is found, SonarQube knows your SDK is being used, so the relationships will be matched automatically with the target you specified.

Defining architecture patterns

A pattern is a named set of three things:

• Components: the parts the pattern expects, such as api and impl. These represent a package or folder in your project and will be matched by name in the context the pattern is used.
• Relationships: which of those components may depend on which. Any relationship you do not allow is forbidden.
• Interface design: which components can be reached from outside the pattern. Think of it as visibility rules that are language independent.

To create a pattern:

1

Create the pattern

Go to Enterprise architecture > Patterns, click Create Pattern, and enter a Pattern name.

2

Add the components

Under Structure, use Add child component to add each part the pattern expects.

3

Allow the relationships

Draw a relationship from one component to another for every dependency you want to allow. Anything you leave undrawn is forbidden, the same rule the intended architecture editor uses.

4

Set visibility, if you need it

Turn on Enable interface design, then mark each component public or internal. A public component can be reached from outside the pattern; an internal one cannot, so a dependency reaching into it is a deviation.

5

Save

Click Save. The pattern becomes available to every project in the organization.

A pattern does nothing until a project adopts it. A tech lead applies a pattern by binding it to a container in that project's intended architecture. From then on, deviations from the pattern are raised exactly like deviations from the rest of the intended architecture: they appear on the project's Deviations page and raise SonarQube issues that developers resolve in their normal workflow.

This is what makes a pattern different from a written convention. Every analysis checks the decision in every project that adopted it, and editing the pattern changes what is checked everywhere. Whether a deviation blocks a merge is up to your quality gate, the same as any other issue.

Permissions

Patterns, SDKs, and system components are defined once for the whole organization and require the Administer architecture permission.

Mapping a project's exit points requires the Administer architecture permission on that project, which project administrators have by default.

Limitations

• The languages supported are C#, Java, JavaScript, Python, and TypeScript. Calls made from code in any other language are not detected.
• A project appears on the map only after it has been analyzed. Until then it is counted among the projects without relationships.
• Automatic mapping requires an exact match between an exit point and an entry point. Everything else has to be mapped by hand, or described with a system component or an SDK.

Related pages

• Architecture analysis

• Project architecture

• Product release lifecycle