The C4 model has become a popular way to visualize software architecture, neatly separating the visual description of a software architecture into distinct layers of abstraction. It also highlights the importance of labeling, to ensure that diagrams are self-descriptive. Ardoq supports C4 model visualization of application architectures. This article explains how to adopt it in a way that is consistent with the metamodel used in the Ardoq Use Case Solutions.

The C4 model uses 4 levels of abstraction to organize different views of an application architecture. The same model is being viewed at each level, but the chosen level of abstraction determines how much detail is shown or hidden from view. The four levels of the C4 model are:

Ardoq supports visualization of levels 1 to 3. As Simon Brown, the originator of the C4 model, suggests, level 4 is “an optional level of detail and is often available on-demand from tooling such as IDEs” (https://c4model.com/#CodeDiagram). We assume that you have an understanding of the C4 model and the elements involved. If you need a primer, please visit https://c4model.com/. This article will follow the same example that is used in that website.

There is a parallel between these four levels and different roles within architecture teams. Level 1 corresponds with the work of Business and Enterprise Architects. Level 2 sits within the domain of Solution Architects, as it deals with the breakdown of business systems into their constituent parts. Level 3 sits with the Software Architect, while Level 4, dealing with code, relates to the work of the Software Designer.

Whilst Ardoq supports levels 1 to 3, most organizations will not need to capture the detail involved in Level 3 in their Enterprise Architecture Repository. In line with the principle that you should only represent in Ardoq things that contribute to answering valuable questions, the joint interests of Business, Enterprise and Solution Architects can be best served by modeling business systems to levels 1 and 2 in Ardoq. Detailed documentation of software solutions at levels 3 and 4 can often be more effectively managed by local development teams using tools such as Lucidcharts, which can then linked to Ardoq components.

Solution Architects will also want to extend their level 2 models to represent technologies and deployment designs. This goes beyond the scope of C4 model diagrams, but is easy to adopt in Ardoq to provide more complete views of solution architectures.

At Level 1 (Context), just two element types are used: people and software systems. As the “people” in C4 models do not represent named individuals, we use the component type Role. And we use the Application component type to represent software systems. To remain consistent with Ardoq’s recommended metamodel, we use two reference types to connect the elements: Connects To for the references between Applications, and Consumes for the references between Roles and Applications.

In C4 models, Role components are used as stand-alone abstracted representations of sets of skills, competencies, behaviors or responsibilities. The same components can also be used to group individuals who perform the same role in an organization. For example, a new business function may require the design of new applications, organizational units and processes. C4 models may be created to document new solution architectures, including newly created roles. As the new function is formed, real people will be assigned to the new roles. The Role components will retain their Consumes references to the Applications and Application Modules that they interact with, while gaining new Is Realized By references to the Person components that represent the actual people who are now performing the new roles. Linking Person components to Role components requires some care and attention. For example, where responsibilities are being assigned, it is important that they are represented in a direct connection between the Person and the item, such as an Application they are responsible for. A Person can be held to account, while a Role cannot. See How to use Roles in Ardoq for a more detailed discussion of the considerations involved.

Using component types from Ardoq’s Use Case Solutions allows your models to be viewed as C4 model diagrams, while also being connected to the wider graph of components that are available to you through adoption of the Ardoq Use Cases. Ardoq’s recommended metamodel is applied consistently across all of the Use Case Solutions, so using Application (rather than creating a new component type called System), for example, allows you to build your C4 models directly into all of your architecture initiatives (leveraging Use Case Solutions such as Application Portfolio Management, Application Integration Management, Data Lineage, IT Cost Management, Technology Portfolio Management and Strategy to Execution). So we won’t be introducing new component types especially for C4 models; we can reuse ones that already exist in the Use Case metamodel.

The Level 1 Context diagram

Level 2 (Container) introduces the container element. As it can be used to variously represent applications or embedded databases, we use the Application Module or Data Store component types from the Ardoq recommended metamodel according to the type required. If your application offers an external interface for integration from other applications, you should model this with the Interface component type. C4 model container elements represent a decomposition of the software systems represented with Applications in the Level 1 Context view. Following our guidance in Should You Model Using Hierarchies or References?, C4 model container elements are created as child components that belong to their Application parent. We use the same two reference types as before: Consumes to link Roles to Application Modules, and Connects To when linking container elements to each other, or to other Applications. Note that when we add the container elements as children of an Application, we replace the references that came into, or out of, the Application with the more specific references to or from its child container elements. This removes any need to manage duplicates, and we will see that Ardoq’s block diagram visualization automatically handles the links for you at every level of abstraction.

Select Group by Parent in your Ardoq Perspective, and you will be presented with your Level 2 Container diagram:

The Level 2 Container diagram

Pressing the “collapse” button at the top left-hand corner of Internet Banking System returns you to your Level 1 Context diagram, automatically retaining the links that connect the application’s children:

Collapsing the Internet Banking System to return to Level 1 Context diagram

You can traverse between levels simply by clicking on the “expand” or “collapse” buttons in the applications that contain child container elements, allowing you to hide or reveal details according to your audience and the story you are telling.

Moving to the next level of detail, creating Level 3 (Component) involves the same process, now adding children to the Application Module components (the application’s containers). The Application has just acquired some grand-children! We follow exactly the same rules that we followed when going from Level 1 to Level 2. Use Application Module, Data Store or Interface components depending on the function of the component you are modeling, and transfer any existing references to the lowest level of component they interact with.

The Level 3 Component diagram

We’ve shown how to apply the C4 model approach to Levels 1 (Context), 2 (Container) and 3 (Component). Not all architecturally driven business outcomes demand modeling software systems down to level 3. You should only model to a level of detail sufficient to allow you to tell the story that you want to tell. See What is an Application? for more guidance on applying this principle.

Finally, it’s worth considering what additional information you may wish to include in your C4 models.

The C4 model approach shows some technology details with each container element. As the approach is only concerned with drawings, this is done directly in each element. With Ardoq we are creating and maintaining a model, so we need to avoid unnecessary duplication of this information (many technologies are likely to be used in more than one container element). If you wish to record technologies in your model, you should add references to your Application Modules and Data Stores from the Technology Product components that make up your Technology Catalog. See the Technology Portfolio Management Use Case for more details of how to do this.

If you wish to show how your software systems have been deployed, follow the guidance in our Application Hosting Use Case. You may also wish to show in more detail how applications are integrated with each other, and the data they exchange. If so, follow the guidance in our Application Integration Management Use Case and our Data Lineage Use Case.

For an overview of the C4 model, see https://c4model.com/.