Creating architecture diagrams with code

[ajmaradiaga]

In this blog post, I will share how you can leverage an open source project called Diagrams to create architecture diagrams with code.

Code to architecture diagram

When explaining to others how a system works or communicates with its different parts, it is generally easier to do it visually, e.g. using an architecture diagram. I've done many architecture diagrams in the past, for which I've used different tools, e.g. Draw.io, Omnigraffle, even Microsoft PowerPoint, and although it is possible to get the job done using this tools, I sometimes found it frustrating how complicated it was to do a minor change in the architecture, rearranging things (PowerPoint 👀), starting from scratch or worrying about using the right icon/colour. These diagrams also change frequently and a new version meant copying the existing file and adding a suffix in the file, e.g. _v1.pptx, _v2.pptx, _v3.pptx. So I was quite happy when last week I found out about Diagrams (https://diagrams.mingrammer.com/).

Diagrams is an open source project which lets you draw architecture diagrams using Python 🐍. Under the hood, Diagrams uses Graphviz (https://www.graphviz.org/gr) to create the diagrams, which is something that I explored before to generate entity-relationship (ER) diagrams from a JSON structure, see Generating Entity-Relationship diagrams from the SAP Ariba Analytical Reporting API metadata. There are various cloud providers included in Diagrams: AWS, Azure, GCP, Kubernetes, Alibaba Cloud and Oracle Cloud. Which got me thinking…. what if we could include the SAP Business Technology Platform Solution Diagrams and Icons, which are publicly available, as part of Diagrams?

⚠️ This is not officially supported by SAP. This is just an exploration of how the official SAP BTP icons can be used within Diagrams.

I forked the original repository and included the SAP BTP icons. Below a sample of how we can use Python + Diagrams with the SAP BTP icons to create your architecture diagrams.

At the moment of writing, the changes proposed to add SAP as a provider in Diagrams have not been merged to the main repository - See pull request 717. In the forked repo, the changes are in the sap-icons branch.

Code sample:

# tech-byte-diagram.py

from diagrams import Cluster, Diagram, Edge

from diagrams.aws.storage import S3

from diagrams.sap.other import Placeholder_Circle

from diagrams.sap.integration import ProcessIntegration_Circle

from diagrams.sap.database_datamanagement import SAPHANAService_Circle

from diagrams.sap.database_datamanagement import ObjectStore_Circle



with Diagram("SAP Tech Byte - Exploring the SAP Audit Log service", show=False):

    with Cluster("SAP Business Technology Platform"):

        with Cluster("Subaccount"):

            cloud_integration = ProcessIntegration_Circle("Cloud Integration")

            object_store = ObjectStore_Circle("Object Store")



            Placeholder_Circle("Audit Log service") << Edge(label="Retrieves entries") << \

            cloud_integration >> Edge() >> SAPHANAService_Circle("HANA Cloud")

            cloud_integration >> Edge() >> object_store

        

    with Cluster("AWS"):

        object_store >> Edge(label="uses", style="dotted") >> S3("S3 Bucket")

The code above will generate the following diagram:

SAP Tech Byte diagram

❓ In case you wonder where under diagrams.sap.* you can find a particular service.... I set up the SAP services in Diagrams so that it resembles the capabilities that have been defined in the SAP Discovery Center. Therefore, if you find the service under DevOps in the SAP Discovery Center, then it is likely that it will be under diagrams.sap.devops.

Now, the diagram above looks great but the colours used by the clusters does not follow the colours specified in the SAP Business Technology Platform Solution Diagrams and Icons guidelines. What if we want to use the colours specified in the guidelines? How would the diagram look? Let’s see…..

Code sample:

# tech-byte-diagram.py

from diagrams import Cluster, Diagram, Edge

from diagrams.aws.storage import S3

from diagrams.sap.other import Placeholder_Circle

from diagrams.sap.integration import ProcessIntegration_Circle

from diagrams.sap.database_datamanagement import SAPHANAService_Circle

from diagrams.sap.database_datamanagement import ObjectStore_Circle



# SAP BTP Solution Diagrams and Icons guidelines colors

L0_BLUE_COLOUR = "#316CCA"

L1_BLUE_COLOUR = "#074D92"

FIX_GREY_COLOUR = "#7F7F7F"

NON_SAP_AREA_COLOUR = "#595959"



with Diagram("SAP Tech Byte - Exploring the SAP Audit Log service", show=False):

    with Cluster("SAP Business Technology Platform", graph_attr= {"bgcolor": "white", "pencolor": L0_BLUE_COLOUR}):

        with Cluster("Subaccount", graph_attr= {"bgcolor": "white", "pencolor": L1_BLUE_COLOUR}):

            cloud_integration = ProcessIntegration_Circle("Cloud Integration")

            object_store = ObjectStore_Circle("Object Store")



            Placeholder_Circle("Audit Log service") << Edge(label="Retrieves entries", color=FIX_GREY_COLOUR) << \

            cloud_integration >> Edge(color=FIX_GREY_COLOUR) >> SAPHANAService_Circle("HANA Cloud")

            cloud_integration >> Edge(color=FIX_GREY_COLOUR) >> object_store

        

    with Cluster("AWS", graph_attr= {"bgcolor": "white", "pencolor": NON_SAP_AREA_COLOUR}):

        object_store >> Edge(label="uses", color=FIX_GREY_COLOUR, style="dotted") >> S3("S3 Bucket")

The code above will generate the following diagram, which uses the colours mentioned in the guidelines.

SAP Tech Byte diagram following colour guidelines

Want to get it running in your local machine?

Below the steps required to run it on a Mac.

# Utilities

$ brew install virtualenvwrapper graphviz poetry



# Clone the forked repository

$ git clone git@github.com:ajmaradiaga/diagrams.git



# Switch to the directory

$ cd diagrams



# Switch to the sap-icons branch

$ git checkout sap-icons



# Build the project using poetry

$ poetry build



# Prepare your Python virtual environment

$ mkvirtualenv sap-diagrams



# Install the package in your virtual environment

$ poetry install --no-dev



# Now you can run one of scripts above locally. This will generate a png file with the output.

$ python tech-byte-diagram.py

That’s it folks! Thanks for making it this far. I really like how fast and easy it is to create simple and complex diagrams using Diagrams + Python. Something that surprised me is that I find the code very easy to read and follow. So much that I believe that someone that is not that familiar with Python, will be able to create and generate architecture diagrams using Diagrams.

[AshGoyal]

Hi Antonio,

That's a very good capability. Thanks for bringing it to fore! I was looking for something like this! Looking forward to more on this going ahead.

best regards,

Ash

[Rui-Nogueira]

Cool blog post Antonio. I'll give it a try as well.

Have you looked at the btp-setup-automator? It helps you setting up a BTP account quickly and I was wondering whether I can use this to visualize a BTP use case that I define as well in a json structure (e.g. a use case for complementing an S/4HANA process in BTP: https://github.com/SAP-samples/btp-setup-automator/blob/main/usecases/released/build_resilient_apps_...).

Would be interested in your feedback on this.

Best,

Rui

[former_member545599]

Great post Antonio, thanks for sharing. I am looking forward to testing it.

 

[IanStubbings]

Hi Antonio

Keen to try this out but having issues with ssh on my mac or order to download from github. Seems there is a problem with OpenSSH?  Just wondered if you needed to navigate round this at all?

Thanks

Ian

[IanStubbings]

Hi Antonio

Actually found a way round this by using a vscode devcontainer with linux os. All good now, works a treat.

Thanks

Ian

[ajmaradiaga]

I imagine this has something to do with how you login to GitHub. Maybe a workaround will be using a personal access token? https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-a...

[ajmaradiaga]

Good to know that you found a workaround. Looking forward to seeing your architecture diagrams in SAP Community 🙂

[IanStubbings]

Thanks Antonio.

Used your examples to start building a coded version of the AWS diagram in my blog post here. I'll have to see how to include the custom images though. Spent a bit of time on the https://diagrams.mingrammer.com/ website in the custom section to understand what is possible and best practice.

Cheers

Ian

[js2]

Hi ajmaradiaga - great tool.

I've found that if I place the script I want to run to generate the diagram anywhere else but inside the diagrams project folder it will miss the icons. So the boxes and lines are drawn but no icons.

If I place the script inside the repository root folder then it all works fine. Any idea? Must be some fixed paths somewhere?

[ajmaradiaga]

Hey jasonscott , thanks for raising this... I noticed that the resources folder is missing when installing the .tar.gz using pip. I've updated the script above to use instead 'poetry install' to install the package in your virtualenv.

When installing it with poetry generating diagrams works fine from any folder, you don't have to be in the project folder.

[js2]

Excellent. Will re-install and try it again. 😉

[js2]

Hmm following the new step with poetry install --no-dev seems to make no difference. Still can not find the icons unless the diagrams script is inside the projects root folder.

[ajmaradiaga]

Odd, as I've been following that same approach with some updates that I've included and it works for me. Maybe I can record a short video and share it here... 🙂

[ajmaradiaga]

I recently included additional icons in the diagrams fork, e.g. SAP S/4HANA, SAP Ariba, SAP Fieldglass, SAP Concur, and more. Let me know if there are any additional #SAP icons that you will like to see in the repo - https://github.com/ajmaradiaga/diagrams/tree/sap-icons

[ajmaradiaga]

I just updated the SAP BTP Solution Diagrams icons.... check it out - https://blogs.sap.com/2023/11/08/quick-update-on-creating-your-sap-btp-architecture-diagrams-with-co....