Subscribe to access the entire course.
🌶️ tip: unsubscribe at any time.
Ah, that's a great question!
Frontend at Scale is a bi-weekly newsletter (as in, once every two weeks) that is all about software design and architecture for frontend engineers.
Subscribing to the newsletter is the best way to support my work and encourage me to keep making free resources like this one.
I probably don't need to say this, but I would never ever spam you—and you can unsubscribe with a single click at any time.
Already subscribed? Don't worry, you won't get double-subscribed. Nobody deserves to read my terrible jokes twice.
Module 3: Designing
[00:03] In this video, I want to talk about a few different types of diagrams that can be really useful during this design phase. Unlike the diagrams that we saw earlier, these are much lower level. These are much closer to the code. So I wouldn’t use them for documentation because they’re going to change pretty quickly or they’re going to get outdated very quickly. But they are good for clarifying your thoughts and they are very good for communication as well.
[00:28] One of the first things that I do when I have to tackle a new functionality or implement a new feature, of my product is grab a piece of paper and a pen and just draw boxes and arrows until I understand what is exactly the thing that I need to do. And once I have a good understanding, I clean up my diagram and I create a virtual version of my diagram. And I use that and I put that in a doc to share with my team and get feedback on it.
[00:54] So that are the main purposes of this diagram that we’re going to see now. Getting clarity on your thoughts and communicating your thoughts with the rest of your team. So I want to go over some of the most common types of diagrams that I typically use. I will go through them pretty quickly, but I will link to some resource in the description of this video where you can learn more about each one of them.
[01:14] I will also give you a resource where you can learn more about mermaid syntax, which is what I’m using here to draw these diagrams and is what I like to use because as I mentioned earlier, these diagrams are typically short lived. They change very quickly. So Mermaid that allows me, allows me to changing them pretty pretty quickly. And I really don’t care about the layout or how nice they look.
[01:35] So I will recommend using any. If you don’t like mermaid, I will recommend using any low effort tool like scalidraw or TLdraw to draw this type of diagrams.
[01:45] The first type of diagram that I want to cover are flow charts or flow diagrams which are good to represent pieces of logic. In this case you have a very simple flow where I just have a condition here and then two different scenarios. But you can imagine that if you have a piece of logic that is very complicated, that has many different steps, many different conditions, or that depends on many different things, then pulling that together visually in a diagram can be really useful and can be a big help during implementation as well.
[02:14] The second type of diagram that I want to share is state diagrams, which, as you might imagine, these are good to represent in changes in state. If you’re using a framework or a library like XState, then these type of diagrams are really crucial and even necessary. You will do a lot of your state management visually using these type of diagrams.
[02:33] But that doesn’t mean that’s the only use case. Anytime you have even like a mini state machine, your application represents something at different states and all the transitions that can happen during those states. Visualizing them using a state diagram can be really useful because it can help you make sure that you are handling all of the possible scenarios and cases that may come up when you actually implement this.
[02:56] Next up, we have class diagrams, which we cover very briefly when we talk about domain modeling earlier, you may argue that class diagrams are really only useful for object oriented programing. And there is some truth to that because that is really the main use case. But as we mentioned earlier, the entities of our system are really these abstract concepts that can be represented in code in a number of different ways, including types or models or even React hooks.
[03:22] So if you ever have the need to represent your entities in a visual way, a class diagram or an entity relationship diagram can be really useful.
[03:31] And the final type of diagram that I want to share is the sequence diagram, which is really useful to illustrate a sequence of operations, especially if those operations are asynchronous. So in this case we have sequence diagram for our order placement process, which involves multiple actors and multiple steps. So it starts with a customer clicking a button and then the web makes a request to core API, core API queries the database then it goes back to Corey API, and then we make up a request through the payment system and then the confirmation go all the way back.
[04:06] This is very simple sequence, but it can already be useful to have some conversations with the rest of our team. For example, we may discuss whether sending just the order ID to the core API is enough or if we need to send other information as well. We may also bring up questions about what happens if the payment service gives us an error. Instead so we don’t have to solve all of those things in the diagram, but it’s good to at least use it as a starting point so that we know we catch all of the edge cases.
[04:37] As I mentioned earlier, you’ll find some links in the description of this video with resources to learn more about this type of diagrams. But we’re going to stay with sequence diagrams for a little bit because that is going to be the topic of our next exercise.