Turning Complexity into Clarity: SitecoreAI Architectural Diagrams That Work

This post was originally posted as part of the Sitecore Community Advent Calendar 2025 the 24th December

As the digital landscape become increasingly complex especially with modern composable solutions and cloud offerings, the ability to clearly communicate how a solution fits together becomes a strategic advantage. Architectural diagrams are more than just technical artifacts, they’re critical tools for aligning teams, accelerating onboarding, and supporting faster, more confident decision-making.

I’ll share practical strategies I’ve found useful for creating and maintaining meaningful, consistent architecture diagrams and the tweaks to easily support the Sitecore product portfolio. With full traceability we are empowering the entire team so your documentation becomes a living part of your workflow and not a forgotten afterthought

Diagrams are a force-multiplier for software teams: they turn complexity into a shared, visual language that speeds decisions, shortens onboarding, and reduces misunderstandings between technical and non‑technical stakeholders.

Find the right level of details

To communicate efficiently with the relevant stakeholders we need to find the right level of details that are relevant for that stakeholder at the point in time. Having too many details will make it more confusing and miss out the important part while too few details make the diagram irrelevant.

One approach I have found helpfull in this balance is Simon Brown’s C4 model¹ from 2017 or something like that. It is inspired by the 4+1 model by Philippe Kruchten² and UML.

It describes a hiearchical set of abstractions and diagrams. It is explained very nicely compared to a geographic maps on the website that I will highly recommend. It is named after 4 levels starting with the letter C:

• Context diagram is very highlevel. What is the scope of the software system, who is using it, what are they doing and which system integrations does it need.

• Containers (component) zooms in on a specific software system and focuses on the major technological building blocks, their responsibilities and communication.

• Components (sub-components) zooms in on the container and showing the parts inside it. It might be exposed APIs, vertical slices or similar

• Code zooms in on a specific component. This is the level that UML usually focus on, actually classes, implementations, compositions etc.

Naming is always hard, what is a container (it is not related to docker at all) and we all know from development with Sitecore that we can get pretty confused about what a component is. They have tried with renaming to component and sub-component which is also a bit confusing in itself when .

I have said that we should always have a Context and Containers diagram on any project. It is usefull for both non-technical and technical participants, it is realistic to product on all projects and it provides substantial value on itself.

Naming is always hard, what is a container (it is not related to docker at all) and we know from all development with Sitecore that we can get pretty confused about what a component is. They have tried with renaming to component and sub-component which is also a bit confusing.

I have said that we should always have a Context and Containers diagram on any project. It is useful for both non-technical and technical participants and it is realistic to have.

When there are certain areas where detailed diagrams can help the conversation and understanding within the team, we can create actual UML diagrams for that specific area.

C4 itself is completely tool and notation independent.

A diagram is only as good as its last update

I think one of the worst things I know is documentation that you can’t trust (ok confusing Confluence sites with plenty of empty pages are close, but there are usually also old and irrelevant meeting notes and other pages - all stuff you don’t know if you can trust).

Therefore the team should own the documentation and the diagrams, it is an integrated part of the software engineering job to take care of multiple areas from User Experience, Editor Experience, deployment, cms items, database updates - maybe documentation for users and editors - keep the code clean and understandable for you and the team - and I say: at least make sure that the existing documentation in the project is still valid.

It is not the same as it should be a Kindergarden or playground where random changes are made everywhere, but neither is it with the code. And we already do have a practice in place to handle this: we are using a repository with versions

At least make sure to have the overall diagrams have processes in place to ensure the diagrams are updated and versioned.

I argue that the diagrams belongs in the source repository - together with the code as an integrated part of the development cycle. It is visible for the developers and makes it clear that when you change code that would make changes to the diagram then you should also change the diagram. Hereby when reviewing Pull Requests it includes both code and diagrams.

Make it easy to make and review updates

We all know binary files in source control is really hard and Git is not really optimal for binaries. So for this reason I don’t really use Visio anymore.

Diagrams in draw.io can be saved as a (formatted) xml file and hereby fits fine in a source repository. I find it is really hard to tell the difference when the file is edited, it is hard to get the essence from all the changes in the xml so I actually rely on a visual diff.

This was probably the reason that I started seeking for another approach.

Don’t get me wrong, the most important part is to have the fundamental and updated diagrams in place and preferably in a versioned way so nobody is worried about making the necessary updates.

If you are happy with Visio files in a Sharepoint folder, a Confluence page (that also can show history), or anything else, please continue. But let me share my journey with you.

Draw.io

A drawing tool that also focuses on diagrams is draw.io or diagrams.net it is called now. With the VS Code extension it is very simple to work with the diagrams with the tool you are (probably) already using for development. The diagrams can be saved as an indented svg file and hereby you can get a lot of the benefits: have the diagrams together with the code repository and empower the team.

Diffing changes to a draw.io diagram is not straight forward as there is a lot of ceremony in the svg file so it can be hard to follow the changes. On the other hand the svg file is immediately usable, you can embed it in your existing README.md file or similar.

If you are doing nothing today and your team is a bit fearful regarding the diagrams, this might be a good starting point. Despite my following (a bit lengthy) arguments for using other tools, you are in a way better place when you have a few diagrams that the team takes ownership for than without.

Diagrams as text is actually superior

It can seems counter-intuitive and fair to say starting to make diagrams in pure text can seem a bit freightening and take a focus on the important part

• simple to make a small change
• simple to avoid making unwanted changes
• simple to see what has changed

Mermaid

You might know mermaid³ already, it is an obvious entry level solution for text based diagrams. It has a simple and intuitive syntax.

It is built in javascript so it is very easy to integrate so there is a chance that it is already available in some of the tools you are using today. If you are using Azure DevOps wiki you can insert mermaid diagrams⁴ and for Confluence there are plenty of integrations.

In mermaid you can write something like

1
2
3
4
5
6

flowchart TD
    V[Visitor] -->|Visit website| W[Website]
    E[Editor] --> |Visit website| W[Website]
    W[Website] --> |Fetch content| S[SitecoreAI]
    W[Website] --> |Product data| P[PIM]
    W[Website] --> |User login| A[Azure Entra]

And get something like:

For what I was seeking regarding the context and container diagram, I found that Mermaid was really limiting, there was from the beginning a focus on flow and sequence diagrams end even though several other types has been added, it didn’t really match my needs and expectations

If you ever find you could improve your wiki pages with an ER diagram, flow diagram, a real UML sequence diagram, or even a Gantt diagram - take a look at Mermaid and there is a high chance that you can easily generate the diagram already in the tool you are working with.

PlantUML

My first real successful work with diagrams based on text was when using PlantUML⁵. It is implemented in Java and distributed as a jar file you can execute from the commandline, but there are also plenty of IDE extensions such as for VS Code⁶ and online editors⁷ that generate the diagram while editing the source file.

PlantUML is actually from back in 2009 but has been continously updated. There have also been focus on UML diagrams but additional types of diagrams have also been added and also a lot of extensibility in the diagrams itself and “standard libraries”⁸. Hence I found a project to add C4 modelling to PlantUML. It was a project on its own so you included the files directly from GitHub but it has since been integrated into the product as one of those standard libraries.

With this C4 library it is simple to write text based diagrams that are almost readable directly from text

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

@startuml class

!include <C4/C4_Context>

Person_Ext(visitor, "Visitor", "Either prospect or exiting customer seeking product info")
Person(editor, "Editor", "Person in marketing department with some responsibility")

System(website, "Website", "The website where the users can read and login and edit stuff")

Rel(visitor, website, "Seeking information")
Rel(editor, website, "Editing pages")

System_Ext(pim, "PIM", "Product Information System where product department manages data")
Rel(website, pim, "Fetch product details")

System_Ext(id, "IdP", "Login for all users and customers managed in Microsoft Entra ID")
Rel(website, id, "Single-Sign-On for users")

@enduml

This will give something like

Clear and readable. When something needs to be added, it could be that we need to integrate with an additional external system or there is a new kind of user of the website, then it is simple to just add an additional line to the file. Just by having this drawing, you can now have the qualified discussion if you see SitecoreAI as an integrated part of the website(s) or if it is an integration to a SaaS product and what the consequences are for the organization.

There is also some configurations that can be added, also in text, eg. SHOW_PERSON_PORTRAIT() and SHOW_FLOATING_LEGEND() and you will get something like:

For a container diagram it could be something like this (follow the link on the image to see the actual source in the online editor):

I should mention that a few years ago Mermaid actually introduced experiemental support for C4 diagrams⁹. It is based on the PlantUML syntax and it is currently still in experimental mode and eg. not available in Azure DevOps.

But I want it nicer, give me colors and icons and… Sitecore

Ok there are plenty of options to style the elements in PlantUML, the UML ground is embraced so all elements can have sterotype(s) and apply styling for all elements of a certain (stero)type.

PlantUML diagrams are actually code, or at least there is a preprocessor. This enables functions and conditions in code and the extensions such as C4 are also “just” functions that creates rectangles with a certain stereotype and text with a reference to a sprite or an image.

There are plenty of those standard libraries eg. to support the major cloud providers with functions that embed the corresponding icon representing a specific service or feature, there are also for Kubernetes, font awesome icons, etc.

After discovering those I concluded that we could also get those for Sitecore, so I have encoded the product logos to sprites and published¹⁰ so you can easily embed those in your own diagrams.

There are many more ways to define styling of diagrams in PlantUML. Each element can have one or more stereotypes you easily apply styling rules to all elements of a certain stereotype, using either skinparams or the newer method is actually css-like stylesheets.

You probably know that SitecoreAI was announced at Symposium in November 2025. Updated the diagram was pretty simple and I think this is one of the major benefits of using a text based diagram tool. Here is a screenshot of the changes in GitHub, it is clear what is changed and simple to review:

It is not just a drawing, it is a model

Due to the preprocessor in PlantUML we have a little coding language. We can split a diagram across multiple files and we can define conditions. It also allows us to more explicitly express intend of the various parts and use the same source for different purposes or perspectives.

Here is a small example of conditionally including ip addresses. For most cases this is too much details and are preventing the overview, but sometimes you need a drawing of your servers, ips etc. and you can have that information collected in one place and rendered when relevant:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@startuml

!include <azure/AzureCommon>
!include <azure/Compute/AzureVirtualMachine>
!include <azure/Networking/AzureLoadBalancer>

!global $showIp = %true()

!procedure VM(alias, name, description, ip)
  !if ($showIp == %true())
  AzureVirtualMachine(alias, name, description, ip)
  !else
  AzureVirtualMachine(alias, name, description)
  !endif
!endprocedure

VM(cd1, CD1, "Sitecore Content delivery", "10.0.0.21")
VM(cd2, CD2, "Sitecore Content delivery", "10.0.0.22")
AzureLoadBalancer(lb, "Load balancer", "https")
lb --> cd1
lb --> cd2

@enduml

Reusability

The preprocessor enables reuse and import of files, even partial inclusion.

I can have a simple solution diagram like this (this example is in the GitHub repository for the Sitecore Plantuml sprites, but inclusion of files requires that you render the files locally eg. in VS Code):

However, by including the SitecoreAI architecture diagram from before inside here, we can in a simple way have a full diagram (that might get too complex, but in the right setting, it might be beneficial)

In the diagram source, the switching between those two are just a matter of !define SITECOREAI_DETAILS 1. I rarely use such a detailed diagram but when introducing eg. SitecoreAI in an organization there might be stakeholders that needs to understand the full picture - and having a toolbox of diagrams that can be applied to the specific solution can really help those discussions.

This can in similar way be used to insert similar content several times. Eg. a diagram to represent a Sitecore solution in kubernetes in a namespace. Hereby it is simple to make a diagram of multiple branches and even feature branches and when they are different (such as using a SQL container pod vs. a managed SQL service) then have this expressed clearly with when and how.

Structurizr

A newer player in the space is Structurizr¹¹. They take the “diagram as the model” approach even further by using a Domain Specific Language (DSL) to describe the architecture and make diagrams to show relevant perspectives of this model.

They have for a while have a paid product that I haven’t had a chance to check by there is also “Structurizr Lite” which is a docker container you can run yourself, the workspace file as volume and use most of the features. There is also a VS Code extension to help with syntax etc.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

model {
    v = person "Visitor"
    e = person "Editor"

    ss = softwareSystem "Software System" {
        web = container "Website" {
            tag "Microsoft Azure - App Services"
        }
        portal = container "Portal" {
            tag "Microsoft Azure - App Services"
        }
        scai = container "SitecoreAI" {
            tag "SitecoreAI"
        }

        web -> scai "Fetches layouts"
        portal -> scai "Fetches content"
    }

    v -> web "Uses"
    v -> portal "Uses"

    e -> web "Edit content"
    e -> scai "Edit content"
}

You can then create system and container diagrams with

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

views {
    systemContext ss "ContextDiagram" {
        include *
        autolayout lr
    }

    container ss "ContainerDiagram" {
        include *
        autolayout lr
    }

    theme "https://static.structurizr.com/themes/microsoft-azure-2024.07.15/icons.json"

    theme "https://raw.githubusercontent.com/jballe/plantuml-sitecore-icons/refs/tags/v2025.1/sprites/structurizr-theme.json"
}

Structurizr also have an answer to one of the things that can be hard when jumping to pure generated diagrams: layout. With PlantUML the layout is completely generated and there are some “tweaks” to influence the layout engine. With Structurizr you can choose to align the elements completely manually like with hand-drawn tools. The alignmening is persisted in a json file (which is hard to read and diff, but when you know it is just layout information)

Diagrams are artifacts

When diagrams or models are described in text files in your repository it might be necessary to also treat them as “code” with build and deploy steps. The concepts are very similar, the image is a representation of the model

Eg. render an image of the diagram and publish as artifact and maybe make it available to a larger part of the organization. If it is publishing a dedicated documentation website or if it is a matter of uploading the images to Confluence, Sharepoint, a wiki or similar.

Ok but what about generation of diagrams, it is just text

Yes because we have text as interface it is “simple” to generate the input for the diagram. And it seems like the holy grail to just generate it all based on what we have.

There are several attempts on this. There are several generators that based on source code can generate class diagrams. As mentioned above, I don’t really find that need for those diagrams, at definitely not for all of the codebase (when documenting certain modules it happens that we create a small diagram for specific concepts).

There are also some attempts on generating diagrams based on Terraform files. It is closer to what we want for a container diagram but I have still not had a really successfull case, often it becomes too granular (with network subnets, security groups, availability groups etc.) and the relations we want to show is actually of a different kind. Maybe you have those expressed as identities and permission rules, but otherwise it is actually something happening at runtime that should cause a relation.

My conclusion so far is, that the overview for Context and Container diagrams are best handled manually.

If you and your team are already totally on top of that and want to improve documentation at deeper levels for certain areas, it might be that you can find generation valuable in some areas. For some more specialized diagrams (such as class, sequence, communication, deployment diagrams) I do see that generation can be helpful. And several source can be used for the generation source code for code and infrastructure, but also telemetry data can be used. But be aware, don’t just generate a bunch of diagrams to put a checkmark and nobody is going to actually use the diagrams.

Key takeways

1. Overall diagrams is a significant assets that helps both stakeholders and developers share view on the solution(s) and easily share important parts.
2. C4 model provides a set of abstractions that helps establish a common baseline and focus.
3. It is significant better to have few updated diagrams than any number of potentially outdated ones. Make sure to have updated documentation as an integrated part of your development flow.
4. By using text based diagrams it can be simpler to diff and follow changes to diagrams in source control, and hereby empower teams to make necessary changes. Consider if that is the right for your product and if some of the examples and techniques can help you get started.