Skip to Content
Technical Articles
Author's profile photo Antonio Maradiaga

Creating architecture diagrams with code

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

Code%20to%20architecture%20diagram

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%20Tech%20Byte%20diagram

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%20Tech%20Byte%20diagram%20following%20colour%20guidelines

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.

Assigned Tags

      12 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Ashwani Goyal
      Ashwani Goyal

      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

      Author's profile photo Rui Nogueira
      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_free_tier.json).

      Would be interested in your feedback on this.

      Best,

      Rui

      Author's profile photo Daniel Burla
      Daniel Burla

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

       

      Author's profile photo Ian Stubbings
      Ian Stubbings

      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

      Author's profile photo Ian Stubbings
      Ian Stubbings

      Hi Antonio

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

      Thanks

      Ian

      Author's profile photo Antonio Maradiaga
      Antonio Maradiaga
      Blog Post Author

      Good to know that you found a workaround. Looking forward to seeing your architecture diagrams in SAP Community šŸ™‚

      Author's profile photo Ian Stubbings
      Ian Stubbings

      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

      Author's profile photo Antonio Maradiaga
      Antonio Maradiaga
      Blog Post Author

      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-access-token

      Author's profile photo Jason Scott
      Jason Scott

      Hi Antonio Maradiaga - 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?

      Author's profile photo Antonio Maradiaga
      Antonio Maradiaga
      Blog Post Author

      Hey Jason Scott , 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.

      Author's profile photo Jason Scott
      Jason Scott

      Excellent. Will re-install and try it again. šŸ˜‰

      Author's profile photo Jason Scott
      Jason Scott

      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.