Visualizing interactions between client, server, controllers and database

[willster000]

When I took this class, I remember struggling to understand how these parts of the program interacted. I knew vaguely that the client communicated with the server and the server had something to do with controllers and something somehow communicated with the database. This knowledge was filled in with particular details on an ad hoc basis (e.g. I would ask a question about http requests and learn some cool details) but I struggled to get an overall picture. If my experience is generalizable at all, then I think giving students a diagram that represents very broadly what's going on between these parts would be helpful. I'll attach a rough sketch of what I'm imagining and if you all it's something you all think is worth working more on, I can do a cleaner, more detailed version. Also, if my rough draft is incorrect or misleading in any way please let me know.

[NicMcPhee]

I think this is a great idea, and something that I think @kklamberty have talked about doing but never actually done. I drew some similar diagrams for some Systems: Practicum labs such as this one:

(This has black lines on a transparent background, so it won't make any sense if you're using night mode.)

Your diagram shows the version "inside" the server side of things. My diagram shows the interaction between a client and a server (but for a different system). There's arguably another diagram that would show how information flows through the Angular client.

I really like your diagram. The one thing I'm not 100% sure about is the return from the controller to the client. I think it might be more accurate to have pass through the server. The controller updates the context, and then the Javalin server code takes that and translates it into an actual HTTP response, which is what is sent back.

So some follow-up questions:

• Should we create three diagrams ("inside" Angular, "inside" the server, and a "big picture" diagram that focuses on the HTTP/network communication? Or is that too many? Should we try to make a single big diagram instead? I worry that a single diagram would be awfully large and complicated. Separate diagrams could then be shared in parts across the various labs.
• How should we draw them? Hand drawn like you've done (nicely)? With Google Docs like I did for the Practicum labs? Something like Excalidraw to sort of split the difference? GDocs has the advantage of making it easier for us to collaborate on them.
• Who wants to draw the diagrams? I'm more than happy to have someone else draft them to start with.

[willster000]

So in our file Server.java, we create an instance of a Javalin server which has built in capability to listen to when the controllers update the context that is received in the http request and then send that updated context back to the client?

And to answer your follow ups:

• I like the three diagrams idea
• I like Exalidraw. I was just playing around with their text-to-diagram AI feature and it's kind of awesome
• I'm happy to create the rough drafts and get everyone's feedback

[NicMcPhee]

Yes, that's essentially correct. When you call things like server.get() and server.post() you're setting up some internal wiring that means that:

• When an HTTP request matching that form comes in, the server parses it and calls the specified method with the context all set up.
• Your code ("the specified method") does whatever it wants to do with that context (e.g., looks up something in the database) and updates the context with the results.
• When your code ends, that returns control back to the server (since it called your code).
• The server then looks at the context for things like the desired result code, JSON bodies, etc., and packages all that up into the actually HTTP response.

And to the questions:

• Let's go with three diagrams.
• I also like Excalidraw. I didn't know about their text-to-diagram AI tool and I'll have to try that!
• Thanks for making drafts!

[floogulinc]

I would just like to mention that GitHub now supports Mermaid for making diagrams right in your markdown. That might be useful for diagrams like these.

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[NicMcPhee]

Very cool, @floogulinc – I didn't know that. Mermaid is very similar to the Graphiv syntax that I know pretty well. I've never done anything fancy with it, but if we could get what we want right in the document (and in version control) that would make it a lot easier to update things in the future. Thanks for the tip.

[willster000]

Here is what I have for an "inside the client" diagram. Its tough to capture the complexity of the process while keeping it visually friendly. If you think I should cut back on detail (e.g. not trace through the code of a specific example like getting users but instead keep it more general), I could certainly try that. My thought is that students will end up replicating pretty much each method shown below when they add new components so if our goal is to make their lives easier, the diagram should include this level of detail but if our goal is to give them more general hints and have them slog through implementation details, then perhaps a higher level, less detailed diagram would be the way to go.

My current plan to continue to trace the get users example over the network, server and database as I have done in the client. If I have time after I get that done and get your feedback, I'll pretty it up a bit. I'm not planning on using Mermaid but if that would really be useful I could try.

One more thing: I realize there are PRs for refactoring both the client and server. I can edit a few things (e.g. adding references user-filter component files) to be accurate to these PRs if they are likely to be merged.

[kklamberty]

I like what you have done in your draft. I think one source of confusion for students has been that we ask them to filter some things in angular and some things on the database, and I think this shows nicely how those work together. At first glance, I was thinking that the angular filtering was incorrectly shown here since it had an arrow off to the right, but that was not pointing at the database since this is the "inside the client" or "inside Angular" view, so that looks right to me.

I think this kind of diagram will help students know what information is being passed around and to where. This might prevent students from making requests to the database for some huge thing so that data is being passed around that doesn't need to be passed around.

If we ever add any authentication to the iteration template or the labs, that would also be a useful diagram.

-KK

On Sun, Jan 7, 2024 at 4:02 PM willster000 @.***> wrote:

Here is what I have for an "inside the client" diagram. Its tough to capture the complexity of the process while keeping it visually friendly. If you think I should cut back on detail (e.g. not trace through the code of a specific example like getting users but instead keep it more general), I could certainly try that. My thought is that students will end up replicating pretty much each method shown below when they add new components so if our goal is to make their lives easier, the diagram should include this level of detail but if our goal is to give them more general hints and have them slog through implementation details, then perhaps a higher level, less detailed diagram would be the way to go.

My current plan to continue to trace the get users example over the network, server and database as I have done in the client. If I have time after I get that done and get your feedback, I'll pretty it up a bit. I'm not planning on using Mermaid but if that would really be useful I could try. client-diagram.png (view on web) https://github.com/UMM-CSci-3601/3601-iteration-template/assets/112008238/faa136dd-3474-4e9a-bb70-b12e1a40d35c

— Reply to this email directly, view it on GitHub https://github.com/UMM-CSci-3601/3601-iteration-template/issues/1405#issuecomment-1880189325, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAU7346MKMJZZPFYORDJKT3YNMLPBAVCNFSM6AAAAABBJQXAD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBQGE4DSMZSGU . You are receiving this because you were mentioned.Message ID: @.***>

-- K.K. Lamberty, Ph.D. Associate Professor of Computer Science | morris.umn.edu/academics/computer-science/ Division of Science and Mathematics, 600 East 4th Street, Morris, MN 56267 University of Minnesota, Morris | morris.umn.edu @.*** | 320-589-6375 she/her/hers

[willster000]

Out of curiosity, why is there server side filtering? It seems the process could be simplified by getting all the users from the server when ngOnInit is called and filtering that array by all four attributes on the client. Is it just so students can see examples of both approaches? Are both approaches used in the "real world"?

[kklamberty]

There may be cases where you don’t want to transmit data unnecessarily. For example, if the data set is very large, it could be costly in terms of time or memory. The data may also need filtering for something like who is logged in, and filtering at the server could prevent unnecessary exposure of data (since transmitting the data may make it vulnerable to attack).

In the other hand, filtering at the client side may be faster. That’s probably useful for the kinds of sorting or filtering that happens frequently or needs to be a bit more dynamic.

We include both examples because (as you said) we want students to be able to see and understand both.

Sent from Gmail Mobile

On Tue, Jan 9, 2024 at 3:44 PM willster000 @.***> wrote:

Out of curiosity, why is there server side filtering? It seems the process could be simplified by getting all the users from the server when ngOnInit is called and filtering that array by all four attributes on the client. Is it just so students can see examples of both approaches? Are both approaches used in the "real world"?

— Reply to this email directly, view it on GitHub https://github.com/UMM-CSci-3601/3601-iteration-template/issues/1405#issuecomment-1883847241, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAU73454M22ZO7ZV5DRVVDLYNW25BAVCNFSM6AAAAABBJQXAD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBTHA2DOMRUGE . You are receiving this because you were mentioned.Message ID: @.***>

[willster000]

Sorry, I was not able to finish this issue. I probably will not have time to do so this semester. If its something you're interested in, I could resume work on it over the summer or next fall.