Technical Articles
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 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.
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
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
Great post Antonio, thanks for sharing. I am looking forward to testing it.
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
Hi Antonio
Actually found a way round this by using a vscode devcontainer with linux os. All good now, works a treat.
Thanks
Ian
Good to know that you found a workaround. Looking forward to seeing your architecture diagrams in SAP Community š
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
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
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?
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.
Excellent. Will re-install and try it again. š
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.
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... š
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
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-code/.