Application Flow Exercise

[00:00:00]
>> David Khourshid: Okay, so what we're going to do is we're just going to brainstorm. This can be for a hypothetical flights booking app, or it could be for any sort of project that you're working on. We're just going to take a nice calm five minutes, and I want you to just roughly diagram those three different types of diagrams for whatever you're thinking of.

[00:00:24]
So, for example, for a flight booking flow, you might want to document the different entities, such as the flights, the hotels, the bookings, etc, or you might want to model something else. Then you would want to model the sequence diagram. So basically, how do the different actors talk to each other?

[00:00:43]
So you might have a flight search service, et cetera, and then just briefly document the flow. Again, this does not need to be for this travel travel application. It could be for anything that you're working on or anything that you might want to build yourself. So the point of this is just to get used to thinking about modeling your application state.

[00:01:13]
All right, so let's talk about just making a flow for, again, anything you wanted to do. It could be a flight booking flow. Or what I'm actually going to do is I was just on Airbnb, and they have a new design, a new interesting flow for actually booking a place.

[00:01:32]
So the idea is that with Airbnb, we have different entities. So first of all, we have the destinations. So we could say we have destinations and we also have different types of. Let's call them homes. So a destination, you know, it might have, like an id, and a home might have, like an id, but also it has a destination id, because these homes don't just roam around, they're fixed to a certain destination.

[00:02:11]
And of course, we also have users as well. So a user, they have a name, they have an id. This is just keeping things very simple. But this goes to show you that modeling these three different things can be very simple. You don't have to prescribe to any specific framework or anything like that.

[00:02:33]
Then we also have the sequence diagram where once we make a search. So in the ui, we are actually calling out to. Let's just call this the Airbnb. Airbnb search service. And so we are saying, find search results for this query. And the query is like, where, check in, check out, and number of guests.

[00:03:09]
Again, I'm doing this in plain language. And so the Airbnb search service. So Airbnb search service will respond with the UI and give us results, and then we will select one. So this is one of those relationships where the UI is basically talking to itself, where we select a home and then we start talking to.

[00:03:38]
Let's just call this the Airbnb API, where we will say that we want to make a booking, and then the Airbnb API will go back to the UI and say, okay, here's the payments information. And then the UI will communicate with the payments processor, etc. And then there's the state diagram.

[00:04:03]
So what's interesting with Airbnb is it actually has a new flow in that top bar. So it's actually pretty cool. If you go to airbnb.com you select Unexpected state, but you select a destination or yeah, you search destinations like Chicago. Oops, Chicago. And then it immediately transitions you to check in, check out, and then you add your guests and then it takes you to a search page.

[00:04:39]
I have no idea what I just searched for, but these houses look really nice. And then it just shows you all of these search results over here. So we can sort of model that flow where first we say, starts with destination, when the destination is input, put in the check in date, then put in the checkout state, then add the number of guests.

[00:05:09]
And then when the user presses search, it'll take us to a search results page. The search results will be loading and eventually show up. The user can click on one of the homes and be taken to a details page. They can go back from the details page back to the search page.

[00:05:41]
So these don't really look like diagrams right now. They're really rough representations of them. But honestly, just doing this is going to be very impactful for just documenting what happens in your application. And so what we could actually do is, for example, I could ask here, we'll just do a new one.

[00:06:05]
I could ask Claude to say, make this a mermaid diagram. And so what it's going to do is it's going to create that diagram and then we could actually copy this and go to something like, I think it's called Mermaid Live. And then we could paste that. And so just from that, we have our representation of the different entities in our application and we could even have it build it out.

[00:06:45]
So same thing with this rough sequence diagram. So create a sequence diagram in Mermaid. And also you could ask it to add things I might have missed. And so it's going to generate that, and then we could just use that thinking for a bit. But the main purpose of this is that even though you're writing in plain language, having this is going to be very useful for not only your teammates, but also assistive coding.

[00:07:22]
Tools and. Wow. Okay, so it does have a very comprehensive, sort of hard to zoom here, but a comprehensive flow of how the different actors interact with each other. So once we have search results, we request home details, the user initiates booking, and that's going to create a booking request.

[00:07:43]
This is probably a lot easier to see in Swimlanes IO, but you get the idea. You have diagrams that you could generate just from the plain text that you write. And so that's why my point in all of this is just write this out. It takes a minimum amount of effort and really you could derive so much from this.

[00:08:07]
So let's do one more. We're gonna take this state diagram and make this a mermaid diagram too, because mermaid also supports state diagrams as well. All right, so it's going to generate that. And now that we. Oops, we actually got it. Now that we have that state diagram, we could visualize it in Mermaid.

[00:08:40]
And it's a bit broken. See if this does anything. Nope, it requires you to sign in. So let me do something different, okay. Make this an XState machine just for fun. Let's see what happens. It's actually filling in context and things like that. And this actually goes to show you too, that you can generate these machines and not even use them in your own application, but even use them just for visualization.

[00:09:21]
So if we go back to state new and we import this, then hopefully, there we go. We have our entire flow documented right here and able to be exported visually. And you saw that it really didn't take much effort to do that. So we're entering the destination, then once we input the destination, we're entering the check in time, then the checkout time, then the number of guests, and then we start searching.

[00:09:54]
So we search for homes. It also handles things like if there's an error, we should handle that error and retry. And then we're viewing the search results and then we're viewing the home details and then we go back to the results. All of this information is really important to keep in mind when you're either building your applogic or working on existing legacy apps, where you might not be sure, like, okay, how does this flow work?

[00:10:20]
Using these AI powered coding assistants, or even just going through the UI and documenting it yourself makes the application logic so much more clear and it gives you a good foundation for if you need to refactor your code base or you need to add features or fix bugs, you do have that outline.

[00:10:39]
So in the same way that we wouldn't build a house without a blueprint, I would not work on an application without documenting it or modeling it, at least at a rough text-only level. So this just shows you how powerful and how easy it is to actually document your application logic.

[00:10:59]
I like to have a Flows MD file where you basically have all of this documentation. Again, it doesn't need to be a specific format and it just needs to be somewhere where both your teammates and also the LLMs and AI tools that you use can easily read it and understand at a higher level what's going on.

[00:11:19]
So any questions about that? Okay, there's a comment in the chat that they can imagine that hooking something like this up alongside Storybook would really help from documentation of components. Yeah, that's true. And another thing that I really want to emphasize is keeping this inside of your code base has two benefits.

[00:11:50]
First of all, like I talked about, both your teammates and AI powered coding tools are going to be able to take that as context and to better understand your code base. And the second thing is it's version controlled alongside your application. If you're storing it somewhere else like notion, that becomes a lot more difficult to do.

[00:12:11]
So that's why I like having a Flows MD file just documenting the app logic. Or you could shove it into the readme MD however you and your team prefers.