Essential Modeling Diagrams

[00:00:00]
>> David Khourshid: There's three essential diagrams that I think that are important for everyone to learn and to use in their application. Again, we're not going to be going full uml. There's many different diagram types, but there's three in particular that really help you think about the incidental complexity in your application.

[00:00:18]
The first is entity relationship diagrams. Now some of you might have worked with this before in databases. And the point of this kind of diagram is to model your data, so documents your data model and the relationship between the different entities in your data. So for example, if we're creating a booking system, we might have a user.

[00:00:40]
Of course most apps have users. We might have flights as well, where this is just a raw list of flights data that we have, and also hotels too. And then we have bookings. Now this is where we get into primary keys and foreign keys. But all that means is that this entity belongs to or is related to another entity.

[00:01:05]
So in this case, a booking might be related to a specific flight or a specific hotel. And there's also the concept of relationships where something can be related to something else and there's a different degree to which they're related. So one thing can have many of the other thing or you could have a many to many relationship as well.

[00:01:28]
There's just different ways of modeling your data. Now, I wouldn't say that you should use a strict tool or framework for doing this. Just list out all of the different entities you have and put it down. Put down all of the properties and also put down how they relates to each other.

[00:01:48]
So the main point I want to make here with entity relationship diagrams is that it's not strictly for databases. It also really helps you model the data in your front end application too. My preferred tool for this, I really like using dbdiagram IO. It's a very simple tool to use and it has a nice, it has a nice DSL over here which again very simple.

[00:02:18]
You have different entities which they call tables. I'll zoom in a little bit here. Then you can model the different properties and the different relationships between each of the entities. You could drag it around and you could include this as a visual in your application just to show these are all of the different bits of data that we're going to be representing and, and this is how they all connect together.

[00:02:46]
So the second tool, or sorry, the second kind of diagram that I really enjoy using is sequence diagrams. So if I go down here, sequence diagrams, they document the flow between different parts of your application. So let's Say that you're searching for flights or something like that. You have the UI and then you have also a flight search.

[00:03:14]
It could be a service or something like that. But the idea is that your UI needs to communicate with this flight search, which can be represented by an async function. But the point is we're sending data from one actor that we call to another actor, and that actor might send, hopefully might send data back.

[00:03:35]
And then in the flow of our application, different actors are going to be talking to each other. So let's say that we have an example, a travel booking flow. The UI might call a FlightsearchService, so that again async function and then that will return results. And then once that happens, our UI will now call a different service and then it will show options, then we will pick one of those options.

[00:04:05]
And then in the UI we might be talking to our own applications API, which can be a different type of actor, where we would create a booking, update the booking, delete it, et cetera. So just being able to document those interactions between different actors is really going to help clarify how the different parts of your application work, especially when it comes to what happens outside of your react components.

[00:04:32]
Now, again, making a sequence diagram, just like making an entity relationship diagram, it doesn't require you to whip out a whiteboard or a diagramming tool. This is something that you could do just in plain text like this. If you do want to use a tool, I really recommend swimlanes.

[00:04:51]
Swimlanes is a very easy to use tool that again, it has its own dsl. It's very expressive. You could change the names of the actors over here and it updates immediately, some message here. You could also add notes and things and you could share and export these diagrams and use it within your own code base.

[00:05:16]
Now the third one, sort of my specialty again, I have lots of courses on, on state machines, but it's the state's diagram. So this documents, what happens inside of your application. So it's not really about sequence diagrams where one actor is talking to another actor, but instead it is the behavior of a single thing, which I like to call actors.

[00:05:44]
So for example, when we're talking about this flight's booking flow, a state diagram might show you the different steps of it. So just to demonstrate here, if we go to states new, let's make a blank canvas over here we might have a flight booking flow, where first it will be flightsearch, and then we'll have our flight results and then we might have the the hotel search, once we pick one.

[00:06:15]
So this is select flight. So then we search for a hotel and then on results we have our hotel results and then we're going to go to a confirmation screen. So when we select a hotel we'll go to review screen. And then let's say that just in this example, let's say that this is where we make our payments, then we go to a confirmation screen.

[00:06:47]
So looking at this, it might seem pretty linear, it might seem pretty simple. And also I want to ask, are you all familiar with state machines? A little bit? Okay, so for those watching, if you're not, a state machine consists of basically three main things. We have the initial states and all of these states over here.

[00:07:09]
And these represents, they could be different screens, different modes of your application, or just different pages. When you're working on multi step forms or flows like that, it's easy to imagine each one of those steps as a state. Then we have transitions. Transitions are what cause one state to go to another state.

[00:07:33]
So let's say that we have our flight results and we select a flight. Now we're going to transition to the hotel search page. And so that's what these are, these are events. Events cause state transitions. So the reason that this is useful is, I mean over here it might be simple.

[00:07:55]
You might be looking at this and thinking, why can't I just write an array of steps, words like flight search, flight results, hotel search, hotel results, review and confirmation. And that's because especially as your app grows in features, it never remains this simple. So for example, let's say that we want to go back.

[00:08:15]
Even the simple act of going back. Now this becomes a directed graph instead of a nice linear structure. Some of you might be thinking, okay, this is a double linked list. But still no, overall it's a directed graph. And then same with hotel search. We could go back and say, okay, we actually want to see the flight results.

[00:08:39]
Again, same thing here. We could go back and then review. Of course, we could go back. And then, this is a key point and why I'm doing this. When we made the confirmation, should we be able to go back? Probably not. So that's why it's important to explicitly model these dates.

[00:08:59]
And in the review too, we might decide that we want to for instance change our hotel search. So change hotel over here. Or we might want to also change our flight. So we might want to go back to the flight search over here. And now, hopefully you could see that this becomes really a directed graph.

[00:09:24]
It's no longer A links list. It's no longer a doubly links list, it's no longer a simple array of steps. But instead this state diagram or flow diagram documents all of the different paths that you have to consider. We could just go through each one and see just all of the different paths that can happen.

[00:09:46]
This is useful not only for modeling your application logic, but also for just modeling how you test your application, whether you're doing it manually or, or you're writing end to end tests. So it becomes very clear to see, okay, here's all of the different things that we could do when we're in each state.

[00:10:07]
Now, state machines and state diagrams are a really great tool for thinking. They are not something that you necessarily need to include in your entire code base. But again, just being able to document the flows are going to, you know, just pay dividends in your state management. And also you don't necessarily need to just go and diagram these state machines.

[00:10:32]
What I like to do sometimes is just write out the different states. So I might say, like starting out here, this is what the user sees. We might not have any data yet, but then they'll fill a form in search and then we will kick off a flight API call and then we're searching for flights.

[00:10:52]
So basically we're documenting each of the screens that we see or each of the steps, and we're also documenting what can happen in each step. Those are the two main important things when you're documenting these state diagrams, what state you're in and what can happen in each state.

[00:11:12]
So any questions before we move on to the exercise on these three different diagram types?
>> Speaker 2: James in the chat just says he's definitely going to take the state machine approach on his next project.
>> David Khourshid: That's awesome. So taking the state machine approach on your next project is a really good idea.

[00:11:35]
Again, it's not something where you have to tell everyone to use XDATA or to refactor everything as a state machine. Just documenting these flows goes a really, really long way. Someone said we're close to the X date topic here. And yeah, all of this, it is influenced from me thinking about state machines, state charts and working on X dates, but we're not going to be talking about X date specifically in this workshop.