4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.

io | Better Programming

Open in app

10
Search

Create Interactive Story-telling Technical

Diagrams With Draw.io
Write more engaging technical articles

Rinagreen · Follow
Published in Better Programming
12 min read · Dec 13, 2021

Listen Share More

Photo by John Schnobrich on Unsplash

Stories and pictures are simple yet powerful tools that help the human brain absorb
new knowledge more comprehensively and remember it longer. In the context of
technical writing, wouldn’t it be great to leverage both instruments to create

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 1/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

profound explanatory diagrams that would communicate complicated technical

aspects of software architecture and business logic?

One of the most popular graphical instruments — draw.io — provides functionality

for creating interactive diagrams allowing you to tell stories about software
architecture without overloading them with excessive information.

What to expect from the article?

In the article, we will consider a hypothetical microservice that processes Users’
profiles — Profile Service.

Among all scenarios (stories) that the service implements, we will cover three
essential ones, namely:

1. saving a profile to the database when a User creates it on the website;

2. indexing profiles in a search & analytics engine;

3. searching for profiles by certain criteria (using the mentioned search &
analytics engine).

Despite the prefix ‘-micro’, the service contains several modules, interaction of
which enables its performance. Those components are:

Profile Service API (hereinafter API)

Profile Service Indexer (hereinafter Indexer)

Profile Service Receptionist (hereinafter Receptionist)

For this service, we will create an interactive schema that explains its architecture
(the relationships between its components) in the context of its business purpose
(the scenarios it implements). To do so, we will use draw.io with its layering feature.

So, if it sounds like something you would like to participate in, let’s start.

Setting up the background

An interactive diagram is a layered diagram — on the same diagram, there are
several views (layers), each of which groups logically related components.

The background layer is the core one and should depict those elements that will be
parts of other layers. The background layer is displayed all the time regardless of
https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 2/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

whether other layers are switched on or not.

The background layer on the schema for Profile Service will represent the service’s
internal organization. It will contain only the components (modules) of Profile
Service with no relationships between them:

Although the service interacts with other software — the website where Users create
their profiles, a search & analytics engine, a database, etc. — we deliberately don’t
display them on the background layer. They will appear later on the corresponding
scenario layers because they are parts of the logic, not the internal organization of
Profile Service.

A control panel for the schema should also be placed on the background layer. The
control panel consists of buttons to display and hide the scenarios. Colored arrows
in buttons will help to differentiate the stories on the schema. Additionally, you can
add an area where descriptions of the scenarios will appear:

At this stage, the diagram looks as follows:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 3/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Important notes
Components of Profile Service are now in grey. In such a way, we emphasize
that they are inactive for now. Later on, when they appear in a particular
scenario, we will change their colors appropriately.

The Description area will contain algorithms for the scenarios so that when
readers switch on one of them, they immediately can read the corresponding
story. However, there is a limitation — only one scenario can be displayed in the
area. We will come back to this restriction in the section Adding Interactivity.

Scenario 1. Saving a profile to the database

To create the layer for Saving a profile to the database, we need to understand what
happens within the scenario from the technical perspective.

How it works
After a User submits a profile on the website:

1. The website sends a message with the profile to a corresponding message

queue. The message queue stores the profile’s data until a responsible software
(consumer) has enough resources to process it.

2. Receptionist — the consumer of the queue on the Profile Storage’s side — “listens’’
to the message queue. When it has enough capacity, it takes the message with
https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 4/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

the profile from the queue.

3. Receptionist then validates the profile according to a particular set of rules and
saves the profile to the database.

4. Receptionist also sends a message with the profile ID to another message queue
that stores IDs of profiles to be indexed.

On the diagram, we will depict this logic on a separate layer named ‘S1. Saving a
profile to the database’. So, before adding any new elements, we

1. add a new layer with the corresponding name in the Layers panel;

2. lock the background layer (by clicking on the lock sign and making it dark-grey)
so that new elements won’t appear where they don’t belong;

3. switch the focus to the newly created level by clicking on it:

Let’s look at the components to add to the layer:

New elements — website, database, two message queues

Profile Service’s modules involved — Receptionist

Now, we are ready to picture the flow described in the “How it works” section:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 5/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Important notes

Elements that are not parts of Profile Storage but involved in the logic are dark
grey.

Receptionist is the only active module of Profile Storage in this scenario;

therefore we changed its color from grey to blue.

In the Description area, we put the algorithm for the scenario so that readers
can match the arrows on the picture and their meanings.

The button Saving a profile on the control panel is blue on this layer, indicating
that this scenario is currently selected for display. We can’t change the color of
an element that is a part of another layer (Background). We need to copy the
element from the layer it originally belongs to, paste it on the current layer,
change its color (style), and move it on top of the original button:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 6/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Usually, one microservice module can’t perform two different activities — it

contradicts the Single Responsibility Principle. In our case, Receptionist doesn’t
take messages from the queue and saves data to the database. For the second
operation, it uses other classes of Profile Service. If you need a more detailed
diagram, you can depict all Profile Service’s classes on the schema. But for our
example, we will omit those details.

Another technical scenario hides behind the words ‘the website sends’. In this
scenario, at least two site components — the client’s side (front-end) and API
(back-end) — take part. But we combine these elements into one entity —
‘website’ — because they don’t directly relate to the business logic or the
architecture of Profile Service.

At this stage, it’s too early to add interactivity to the diagram. First, we need to create
all layers. Then we can work on switching between them.

Scenario 2. Indexing profiles

Applying the approach we used for the first scenario, we will create a layer for the
second one — Indexing profiles in a search & analytics engine.

If you are new to the concept, indexing of data is a way of storing the data in a special
place (index) to be quickly found and retrieved on demand. You can think of an
index as a database with sophisticated searching mechanisms. ElasticSearch is a
search & analytics engine commonly used to create extensive data indices.
How Indexing of profiles works
1. Indexer — the Profile Service’s module responsible for indexing of profiles —
takes the message with the profile ID from the indexing queue.

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 7/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

2. Indexer then sends a request to API to get profile data by the profile ID.

3. API gets the necessary data from the database.

Again, API uses other Profile Service’s classes to do so, but we are not at this
specification level.

4. API returns the profile data to Indexer.

5. Indexer transforms the profile data into a format suitable for indexing (for
example, JSON) and saves the formatted profile to a corresponding index in a
search & analytics engine (SAE).

On the diagram, we will depict this logic on a separate layer named ‘S2. Indexing
profiles’. So, before adding any new elements, we

1. add a new layer with the corresponding name in the Layers panel;

2. lock both the background and ‘S1. Saving a profile to the database’ layers (by
clicking on the lock sign and making them dark-grey);

3. switch the focus to the newly created level by clicking on it:

On the layer, we have:

New elements — Profile index in the SAE

Existing elements — database, the indexing message queue

Profile Service’s modules involved — API, Indexer

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 8/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Let’s put on the diagram the flow described in the “How Indexing of profiles works”
section:

Scenario 3. Searching for profiles

We won’t describe the whole process in detail for the remaining scenario. The
approach is the same, so it will be enough to explain How it works and show the
final view of the diagram layer.
How Searching for profiles works
Searching for profiles implies that a User wants to get only those profiles that meet
certain criteria. To do so, they specify filters on the website and click on the button
Search for profiles. After that

1. The website sends a request to API to get profiles by the specified criteria.

2. API gets suitable profiles from the Profile index in the SAE.

3. For the retrieved profiles, API gets additional data from the database.
This step can be omitted if the Profile index stores all the needed parameters for

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 9/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

each profile. But if, for example, information about skills that Users manually
add to their profiles is not stored in the index, it will be retrieved from the
database on this step.

4. API returns the resulting set of profiles with all needed information to the
website (to the User).

On the diagram, Scenario 3 looks as following:

Important notes
1. The optional step is depicted as a dashed arrow.

Adding Interactivity
At this point, we created all the layers for the schema, and readers can already
switch between them using the Layer panel. So, do we actually need to add any
interactivity?

If a diagram is embedded into a page on a CMS platform (Confluence, for example),

it is quite tricky to find the Layer panel in the top hidden menu of the schema.

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 10/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Having interactive buttons to display and hide certain scenarios seems more user-
friendly. Besides, everything becomes better when it is clickable.

The background layer is the first one that readers will see. Therefore, buttons in the
control panel of the background layer should respond to clicks and show the
corresponding scenarios. Let’s add interactivity to the Saving a profile button.

1. In the Layers panel, click on the S1. Saving a profile to the database layer;

2. In the bottom menu of the Layers panel, click on the pen icon to open the layer
for editing;

3. Copy the layer’s ID:

4. Switch to the Background layer of the diagram:

lock and hide all other layers (S1, S2, and S3);

show and unlock the Background layer;

set focus on the Background layer.

5. Right-click on the Saving a profile button and select Edit Link… in the popup
menu:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 11/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

6. In the first text area, paste the following code:

data:action/json,{“actions”:[{“toggle”: {“cells”: [“{layer_ID}”]}}]}

{layer_ID} is the S1. Saving a profile to the database layer’s ID copied in step 3.

7. Click on the button Apply:

This code will show the scenario when readers click on the Saving a profile button
on the Background layer.

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 12/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

We use the same approach for the rest of the scenarios. After adding toggle actions
to all three scenario buttons, we have the following result:

Important notes

1. As we said before, the Description area can hold only one scenario at a time. So,
only an algorithm of the top layer among the selected ones will be displayed.

Now, readers can switch ON particular layers, but they can’t switch layers OFF. To
enable readers to hide scenarios, we will add hiding actions on the corresponding
buttons. Unlike showing actions added on the Background layer, hiding actions
should be added on the scenario layers.

Let’s look at the Saving a profile button. To hide the corresponding scenario, we

1. Switch to the S1. Saving a profile to the database layer of the diagram:

lock and hide all layers except Background and S1. Saving a profile to the
database;

show and lock the Background layer;

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 13/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

show and unlock the S1. Saving a profile to the database layer;

set focus on the Background layer:

2. Right-click on the Saving a profile button and select Edit Link… in the popup
menu.

3. In the first text area, paste the following code:

data:action/json,{“actions”:[{“hide”: {“cells”: [“{layer_ID}”]}}]}

{layer_ID} is the S1. Saving a profile to the database layer’s ID.

4. Click on the button Apply:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 14/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

This code will hide the scenario when readers click on the Saving a profile button
on the S1. Saving a profile to the database layer.

We use the same approach for the rest of the scenarios. After adding hide actions to
all three scenario buttons, we have the following result:

The only static button now is the Show/hide all scenarios one.

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 15/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

To add interactivity to this button, we

1. Switch to the Background layer;

2. Copy the Show/hide all scenarios button and paste the copy near the original
one. Change the color and font of the copied button so that it looks like it is
clicked.

3. Right-click on the copied button, select Edit Data… in the popup menu, and
copy the ID of the button:

4. Go to the original button and add the following toggle action to it:

data:action/json,{“actions”:[{“toggle”:
{“cells”: [“{layer1_ID}”, “{layer2_ID}”, “layer3_ID”,
“copiedButton_ID”]}}]}

layer1_ID — ID of the S1. Saving a profile to the database layer

layer2_ID — ID of the S2. Indexing profiles layer

layer3_ID — ID of the S3. Searching for profiles layer

copiedButton_ID — ID of the copied button from step 3.

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 16/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

5. Add the same action to the copied button (the toggle action shows and hides
elements based on their current state — if they are displayed, it will hide them, and
vice versa).

6. Move the copied button on top of the original one.

And we are done — the interactive diagram is ready:

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 17/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Final suggestions
Instead of a conclusion, I would like to add some more suggestions that may be
helpful when you create your own diagrams.

1. Depict only essential scenarios on the schema — To introduce readers to a new

service, choose those scenarios that cover the primary components of the
service and reveal the service’s main purpose. If you want to depict more
scenarios or get deeper into technical implementation, you can create a
Helicopter view schema and additional diagrams with more profound
specifications.

2. Put numbers on arrows — Numbers on arrows help readers to follow the story
you want to tell. They won’t be confused to find the starting point of a scenario
and the final one.
Useful resources
Interactive diagrams with custom links and actions

Work with custom links

The XML code for the ProfileService file is available in this gist.

Writing Technical Writing Documentation Programming Coding

Follow

Written by Rinagreen
175 Followers · Writer for Better Programming

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 18/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

More from Rinagreen and Better Programming

Rinagreen in Better Programming

How to Generate Animated Interactive Flowchart Diagrams for

Documenting Case Scenarios
Build interactive diagrams as a technical writer

9 min read · Apr 19, 2022

352 4

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 19/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Sami Maameri in Better Programming

Building a Multi-document Reader and Chatbot With LangChain and

ChatGPT
The best part? The chatbot will remember your chat history

17 min read · May 20, 2023

1.92K 17

Oliver Molander in Better Programming

DuckDB — What’s the Hype About?

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 20/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

This was a blog post that I already planned to write during the spring when I saw that the hype
around DuckDB started taking new heights…

10 min read · Dec 29, 2022

1.6K 11

Rinagreen in Better Programming

How to Insert Video Content in Technical Diagrams Using Draw.io

Tips to create more illustrative technical blog content

3 min read · Jan 13, 2022

52 1

See all from Rinagreen

See all from Better Programming

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 21/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Recommended from Medium

Wenqi Glantz

2 Simple Steps to Creating Dynamic Diagrams with Draw.io

Exploring Flow Animation in Draw.io

· 3 min read · Nov 2, 2023

671 2

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 22/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Arun Shankar in Google Cloud - Community

Architectural Patterns for Text-to-SQL: Leveraging LLMs for Enhanced

BigQuery Interactions
TLDR: This article delves into the Text-to-SQL domain, demonstrating the growing reliance on
Large Language Models (LLMs) for this complex…

36 min read · Nov 12, 2023

487 7

Lists

General Coding Knowledge

20 stories · 1133 saves

My Favorite Writing Advice & Inspo

15 stories · 653 saves

Our favorite writing prompts and inspiration

15 stories · 229 saves

Stories To Help You Overcome Writer's Block

8 stories · 357 saves

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 23/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Sameer Paradkar in Oolooroo

A Step-Wise Guide to Architectural Decisions

In the rapidly evolving world of software development, the architecture of a system forms the
backbone of its functionality, scalability…

13 min read · Nov 23, 2023

22

ByteWave

Enhancing AI System Design Documentation with Mermaid Diagrams

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 24/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Introduction

· 5 min read · Jan 18, 2024

71

Jakki Rajasekhar Ramana

Convert text into ER diagrams with AI(Eraser,PlantUML)

Sometimes drawing ER diagrams can be tough,one mistake and whole diagram is wrong.Even
slight mistakes can cost the whole ER diagram.

2 min read · Jan 27, 2024

98 1

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 25/26
4/22/24, 1:50 PM Creating Story-telling interactive Diagrams with draw.io | Better Programming

Benedict Neo in bitgrit Data Science Publication

Roadmap to Learn AI in 2024

A free curriculum for hackers and programmers to learn AI

11 min read · Mar 11, 2024

10.3K 111

See more recommendations

https://betterprogramming.pub/creating-story-telling-interactive-diagrams-with-draw-io-f7e57ae32621 26/26