Transcription
Hello everyone, and welcome to my channel! My name is Mikhail Nepomnyashchy, I am a developer, and my website is mb.com. Today, we will talk about sequence diagrams—diagrams that we show to users on the website, as well as diagrams that we use internally to remember things, simplify our thoughts, and communicate with colleagues, negotiate, draft contracts, and discuss the business logic we will work on directly with the client.
We will use a service called Mermaid, which is available at mermaid.js.org. Why this tool? It is very convenient in terms of Markdown. Many of our documents are saved in Markdown today. For instance, if we look at GitHub, we can store diagrams in Markdown code format. These are not just images; they are something we can interact with.
Diagrams can vary in complexity. I have a fairly simple one, and we will draw something similar today. The official website has a lot of resources, including educational materials. We will start with the documentation and see that there are many different types of diagrams: flowcharts, sequence diagrams, class diagrams, state diagrams, and pie charts. There are even diagrams related to Git flow, which can be used for team agreements on branch naming.
However, from what is regularly useful, it is essentially primitive, but it is quite convenient and helpful.
What we will need looks like this: any diagram starts with the name of its type. In our case, it is a sequence diagram. Next, we have something interacting with someone, and I have the name of one participant and the name of the second participant. Between them, there are various arrows—there are many types of arrows, which we will look at in a table below.
Then comes a colon with a description of what exactly should happen. Here, one participant requests something from the other, and the other responds. We see a different type of arrow on the diagram indicating a response, again through a colon. In general, these two types of interactions—request and response—are usually sufficient for me. Most of the time, the client-server communication follows this pattern, or in our application, the interaction can go the same way.
If we go further down, we will see that we also have stick figures for interaction. We will look at how to do this. We have not only complex diagram options but also different color schemes if needed. There are options for using various conditions, and we will look at that too.
Here is a table of what we might encounter. There are many different types of arrows, but I repeat, I only use two of them. Depending on what you are doing, your situation may be much more interesting than mine.
Let's move to the Live Editor, where we will write the code. Here, we see that we already have a flowchart because everything starts with the word "flowchart." We are not very interested in that; we agreed that we would work with a sequence diagram today.
You can start the story in different ways. You can first describe the participants—we will get to that—or you can start writing right away. Here, I have participant one making a request to the server, asking for something, for example, "Give me the data." Participant two responds, saying, "Here are your data."
Accordingly, here is one dash, two greater-than symbols for the request, two less-than symbols for the response, a colon, and a description of what is happening. Essentially, this is all the syntax you need to know.
We see that these names of participants give us rectangles on the right. In general, we can add any number of participants this way. However, the names of participants can be longer or shorter, and it is not always clear what "B" is, for example. Especially since "B" can be turned into something more complex.
Therefore, we have the keyword "participant," and here we can specify that we have a participant named "F." I want to use "F" in my further scheme directly in the code, but in illustrations, I want it to be represented differently. So, I describe the second participant similarly, saying that I will name it just like in the flowchart.
We see that it has also been renamed here. If we want a stick figure instead of "participant," we write "actor," and a stick figure appears. Here, we can argue that we are not really dealing with a person for the server; it will be a browser, a mobile device, or an IoT device like a watch.
In my case, I often just use regular stick figures. I will have four: I will have "D," and I will not give any clarifications on how I want to name it. I will also have some "A" and "B," which in this case will be an external API service.
Why is it convenient to describe participants right away? I started describing some participants in the order I began, and they appeared on the diagram. It is not always necessary to do it this way; sometimes, we can change the order. Here, it is convenient to write participants initially, but in my case, they were positioned correctly from the start.
It is nice to know that we can manage this positioning. In cases where we use caching on the server, we have a slightly more complex interaction story between the client and the backend. We will describe it now.
Let's start by saying that our backend will query Redis directly. So, it makes another request and asks if we have a cache. In the simplest case, we have a cache. We say, "Yes, we have a cache." Accordingly, the response returns some data. After that, we return this data to the client.
But this is one scenario, and there is a possibility that there is no data in the cache, and we want to make a request to an external API to fetch this data. By the way, it does not have to be an external API; it could be a request to a database.
We have a question: do we draw two flowcharts for two different scenarios, or do we try to display everything in one? In this case, we will comment using the same hotkeys as in most editors. I will press Command + /, and we will go down the unsuccessful path.
We will say that Redis responds to our client, saying there is no cache. In this case, we have further interaction with some service. We request data again, return this data, but only two arrows. Then, this data goes directly to the client, but probably not immediately. We should first save this data in the cache.
So, the backend makes a request again to Redis. It can communicate with itself. We do not always want to illustrate what is happening directly at some node, but we can do that. For illustration, we have an arrow pointing to itself, which can often be seen in diagrams.
When the caching work is completed, the backend responds to the frontend. Thus, we have two branches, and the question arises again: do we store two diagrams, or do we make one? We have tools to include both cases in the same flowchart.
It looks like this: I use the keyword "alt" and say that this will be the "Happy path," the successful case. I also need to clarify that we can make an indent here; there can be spaces between the arrows, which are optional. It works both ways.
We can also make this indent or not, depending on what is convenient for us. When we use alternatives, we must use the keyword "alt." For example, we can specify that this is the "No cache" scenario, and then we can indicate where this alternative scenario ends.
I will also do this with an indent to make it clearer. Thus, I have three operations that always work, and here is some variability on the diagram, represented by a dashed line enclosed in the "alt" block. We see the "Happy Path" here, which has only one action, and the second option is also present.
In principle, nothing prevents us from adding more options with different "else" statements. We have a ready-made diagram. Overall, we used basic tools that can be used every day. I repeat, there are many tools, and you can choose a more complex scenario for your tasks.
What to do with all this? I copy what I have created and go to GitHub. Here, I have an empty repository, and I will edit it, giving it a name. It probably makes sense to make it larger.
Here, as with code on GitHub, to insert code, we use triple backticks and specify the language. In this case, our language will be Mermaid. I copy everything I wrote earlier.
In principle, I do not have to save it immediately; there is a preview, and I can check that it displays as I expect. After that, I can commit.
And here is my diagram successfully saved on GitHub, logically using the same syntax with triple backticks at the beginning and end, and marking that we use Mermaid as the language.
We can save our diagrams in various places. These are sequence diagrams, and I repeat, I use them quite regularly. I started using them just this year because I used to draw everything by hand. But I got acquainted with this tool, liked it very much, and now I use it regularly.
They are not complicated but significantly simplify life—like just unloading your head, documenting something when communicating with colleagues, or drafting contracts.
I repeat, when working with business, business does not always understand what we are telling them in technical language. But when there is a clear diagram without code details, the business can point out that something is wrong with the business logic, saying that the arrow should go there or that this step is missing or unnecessary, and so on.
Thus, at the design stage, we can fix something and speed up our further development.
That's all for today. I hope you liked the tool and that you will use it.
I remind you that my name is Mikhail Nepomnyashchy, my website is mb.com, and I have a Telegram channel, Map_channel.
See you in the next videos! Bye everyone!