# Diagramming training ## Overview - why do we diagram? - diagramming is an efficient mode of communication. humans are spatial thinkers - diagramming is an analysis tool. you can figure out complex relationships between things more quickly by using diagrams - https://twitter.com/ruthmalan/status/1427311419251437578?s=21 - what are learning today - we're going to look at one common diagrams: sequence diagram - The best way to get better at diagramming is to do it. - guidelines - don't get hung up on notation. most people don't know uml anyway so basic shapes are enough to start creating diagrams - don't try to overload a diagram with too much information. ## Diagram as code libraries - Popular: [plantUML](https://plantuml.com/) and mermaidJS - HackMD supports rendering diagram as code libraries - we're using plantUML today becuase it's the first diagram framework we're supporting with techdocs and it's preferred by Liberty ## Simple squence diagram ```` ```plantuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response ``` ```` ```plantuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response ``` - Two interacting entities: alice and bob - Alice sends an authenticaing request to Bob - Bob responds with an authentication response - differing arrow styles: solid and dotted lines - [sequence diagram reference](https://www.lucidchart.com/pages/uml-sequence-diagram) ![[Screen Shot 2021-08-18 at 8.35.28 AM.png]] ```ad-tip title: Tips for sharing diagrams - don't get hung up on the accuracy of the symbols unless it's an important quality you're trying to convey. - assume that your readers only understand the obvious symbols and know to read from left to right ``` ## Exercise 1 - Recreate the diagram in HackMD (work on this) - After a successful authentication response, Alice requests user data from Felix. Bob also let's Felix know about the authentication request approval but requires no response. Felix responds to Alice with the user data. Diagram this ```plantuml Alice -> Bob: Authentication Request Bob -> Alice: Authentication Response Bob -> Felix: Authentication request approval Alice -> Felix: User data request Felix -> Alice: User data response ``` ## Refactoring the diagram - What if we want to rename Alice to Alex? With the current diagram we'd need to change it in three spots - PlantUML supports defining your entites separately from their interaction ```` ```plantuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response ``` ```` ```plantuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response ``` this could be refactored as ```` ```plantuml participant requester as Alice participant approver as Bob requester -> approver: Authentication Request approver -> requester: Authentication Response ``` ```` ```plantuml participant Alice as requester participant Bob as approver requester -> approver: Authentication Request approver -> requester: Authentication Response ``` - Two advantage to this approach - diagram code is easier to update because the labels are defined in one place - diagram code is easier to reason through because we're using _role names_ in the interaction defintions ## Exercise 2 - Refactor the diagram from the first exercise to define the participants separately. ```plantuml participant Alice as requester participant Bob as approver participant Felix as provider requester -> approver: Authentication Request approver -> requester: Authentication Response approver -> provider: Authentication request approval requester -> provider: User data request provider -> requester: User data response ``` ## Exercise 3 - This process has been automated. Rename the actors: - Alice is now a React application as a participant - Bob is an Session provider as a control - Felix is a User Data database as a database ```plantuml participant "React Application" as requester control "Session provider" as approver database "User Data" as provider requester -> approver: Authentication Request approver -> requester: Authentication Response approver -> provider: Authentication request approval requester -> provider: User data request provider -> requester: User data response ``` ## Exercise 4 - Add an api (boundary type) called `User Data service` between the database and the react application that validates the token with the approver before returning the user data - Refactor the interaction annotations to document / emphasize the movement of an token ```plantuml participant "React app" as requester control "Session provider" as approver boundary "User data service" as provider database "User data" as repository approver <- requester: request token approver -> requester: send token requester -> provider: send token approver <- provider: send token approver -> provider: send token validation provider -> repository: query user data repository -> provider: return user data provider -> requester: return user data ``` ## Alt flows and groups - you can represent errors or alternative flows with groups ```` ```plantuml Alice -> Bob: Authentication Request Bob -> Felix: Authenication approval alt Authentication rejected Bob -> Alice: Authetnication rejected end Bob -> Alice: Authentication Response Alice -> Felix: User data request Felix -> Alice: User data response ``` ```` ```plantuml Alice -> Bob: Authentication Request alt Authentication rejected Bob -> Alice: Authentication rejected end Bob -> Felix: Authenication approval Bob -> Alice: Authentication Response Alice -> Felix: User data request Felix -> Alice: User data response ``` ## Exercise 5 - Add a failure condition for an expired tokens ```plantuml participant "React app" as requester control "Session provider" as approver boundary "User data service" as provider database "User data" as repository approver <- requester: request token approver -> requester: send token requester -> provider: send token approver <- provider: send token alt Token expired approver -> provider: send token expired error provider -> requester: send token expired error end approver -> provider: send token validation provider -> repository: query user data repository -> provider: return user data provider -> requester: return user data ``` - go over the keywords (boundary, control) - give more time to read the exercise - move slowly read the exercise - describe the react application - provide a github action for deplying mkdocs + plantuml