docs: add server concepts doc

[thulieblack]

Description

• Add a concepts file under docs for the new concepts section

Related issue(s) Fixes #797

[netlify[bot]]

✅ Deploy Preview for asyncapi-website ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	820c32fba7a62fca1cac3b406935ffa976df2507
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/6328ac5726afd50007c8daf8
😎 Deploy Preview	https://deploy-preview-807--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions[bot]]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	42
🟠 Accessibility	88
🟠 Best practices	83
🟢 SEO	90
🔴 PWA	30

Lighthouse ran on https://deploy-preview-807--asyncapi-website.netlify.app/

[thulieblack]

@starlightknown @pratik2315 @nelsonmic @Annysah need help and suggestions for the server definition

[starlightknown]

I see that some tests are failing, I checked and looks like you have to make changes in two more files , would you like to hop on call and I can explain

[pratik9315]

I see that some tests are failing, I checked and looks like you have to make changes in two more files , would you like to hop on call and I can explain

What was the error !?🤔

[thulieblack]

Yes @starlightknown we can hop on a call

[starlightknown]

I see that some tests are failing, I checked and looks like you have to make changes in two more files , would you like to hop on call and I can explain

What was the error !?thinking

the files are not connected

[thulieblack]

@derberg are there resources I could reference too, so I understand AsyncAPI servers better. Because I have questions like why servers are important in the EDA, what impact they have, and the importance they have in the architecture.

[derberg]

@thulieblack I don't have anything specific to recommend, but I can give a hint for google search:

• google for explanation of Websocket protocol and concept of server-client connection, were Websocket server plays important role, and from AsyncAPI perspective where you describe the application, you describe the server of your application, in other words, server is 1:1 your application
• google for broker centric, explanation of Kafka or MQTT where server is not your app that you describe with AsyncAPI, server is a broker to which your app connects to, of your consumers connect to send info that eventually you will take from the broker. I love this kids book on Kafka https://www.gentlydownthe.stream/

I hope that helps. Let me know how that worked, we can jump on a call one day if you have some questions, if you want

[quetzalliwrites]

BIG THANK YOU to @fmvilas @derberg @smoya for being so quick to reply to Thulie's PR and leaving super detailed feedback! ❤️

[thulieblack]

am I heading in the right direction?

[smoya]

am I heading in the right direction?

Yes, I think you are heading in the right direction! There are some things you will need to fix:

• The symbols used are not the most appropriate. As your chart is an architectural diagram and not a flowchart, you could use all symbols you want but some "common sense" could be good to help people quickly identity components on the architecture. Let's see:
  • Producers/consumers usually are just clients or services running somewhere. However, you used the pipe as the shape, which at the end is commonly used for representing queues. I would use another shape (square could be an option, but up to you).
  • Channels can be represented as queues/topics most of the time, so a pipe (the one you used for the producer/consumer) fits very well here IMHO.

Also, maybe it's worth to add some naming on those channels as example. Instead of call them channels, maybe something like channel1, channel2.

I hope it makes sense.

[thulieblack]

Yes, I think you are heading in the right direction! There are some things you will need to fix:

• The symbols used are not the most appropriate. As your chart is an architectural diagram and not a flowchart, you could use all symbols you want but some "common sense" could be good to help people quickly identity components on the architecture. Let's see:

  • Producers/consumers usually are just clients or services running somewhere. However, you used the pipe as the shape, which at the end is commonly used for representing queues. I would use another shape (square could be an option, but up to you).
  • Channels can be represented as queues/topics most of the time, so a pipe (the one you used for the producer/consumer) fits very well here IMHO.

Also, maybe it's worth to add some naming on those channels as example. Instead of call them channels, maybe something like channel1, channel2.

I hope it makes sense.

Like this right ?😉

[smoya]

Yes, I think you are heading in the right direction! There are some things you will need to fix:

• The symbols used are not the most appropriate. As your chart is an architectural diagram and not a flowchart, you could use all symbols you want but some "common sense" could be good to help people quickly identity components on the architecture. Let's see:

  • Producers/consumers usually are just clients or services running somewhere. However, you used the pipe as the shape, which at the end is commonly used for representing queues. I would use another shape (square could be an option, but up to you).
  • Channels can be represented as queues/topics most of the time, so a pipe (the one you used for the producer/consumer) fits very well here IMHO.

Also, maybe it's worth to add some naming on those channels as example. Instead of call them channels, maybe something like channel1, channel2. I hope it makes sense.

Like this right ?😉

Yeah, that looks way better! Completely out of your work here, I wonder if we should create a theme and a set of shapes exclusive for AsyncAPI so we can use the same style on all diagrams we create.

WDYT @alequetzalli @mcturco @derberg @fmvilas ?

[derberg]

Yeah, that looks way better! Completely out of your work here, I wonder if we should create a theme and a set of shapes exclusive for AsyncAPI so we can use the same style on all diagrams we create.

yes, I new at some point someone will mention it. This is why I mentioned to @alequetzalli few days ago that we might want to adopt mermaidjs and forget about any themes, styles, standards as they will be simply enforced by the CSS on the website, as in the end, it is SVG

[quetzalliwrites]

Yeah, that looks way better! Completely out of your work here, I wonder if we should create a theme and a set of shapes exclusive for AsyncAPI so we can use the same style on all diagrams we create.

Yes @smoya, all diagrams in a Docs site should have a theme or branding style guide approved by design, as I noted months ago. 😄

I don't know that we will create specific AsyncAPI diagram shapes tho, since we'll be using UML diagrams most likely for everything right now.

[quetzalliwrites]

Hey @thulieblack! Let me know how you feel so far addressing all the technical feedback from the community. I know they sent a lot of feedback, so just let me know if you are good at working on the next draft or if you need more support. ❤️🎉

[thulieblack]

Hey @thulieblack! Let me know how you feel so far addressing all the technical feedback from the community. I know they sent a lot of feedback, so just let me know if you are good at working on the next draft or if you need more support. ❤️🎉

Hey @alequetzalli so far so good, I'm ready to get started on the next draft😀

[thulieblack]

Hie @derberg, @serg, @alequetzalli, and @fmvilas, thank you so much for the valuable feedback. I have implemented some changes to the server definition. Could you kindly review if I'm heading in the right direction

[quetzalliwrites]

I think we need a separate diagram for websocket

@derberg Do we need to add a 2nd diagram showing a websocket protocol? If so, why specifically are we adding one for websocket vs the other popular ones we have such as kafka? (I'm asking as much for my own learning as for Thulie's.)

I wanted to follow up and make sure we all agree on whether Thulie should add a 2nd one. Altho come to thing of it... It would probably help if you made the diagram and added it for Thulie, because she will likely lack the knowledge to make it. (I would too, I would likely ask you for it or even ask for a call to learn more. haha)

[derberg]

So the idea behind the other diagram, and websocket as example is, that EDA is just not only brokers.

This document focuses only on consumers, producers, channels and broker. It is ok, but it is just one side of the coin. And if we explain only this one side of the coin, we continue confusing people as we are at the moment 😄

So AsyncAPI file, among other information, contains information about servers. In case of broke-centric architectures, the server is a broker. So user uses AsyncAPI to describe Application A, and all the details are about Application A, except the server as the server is actually a broker, to which consumer has to connect to be able to send and receive messages related to Application A.

Now, in case of websocket for example, case is different. AsyncAPI file for WebSocket Application A (WAA) will have information about server that actually points to WWA and not some external broker. So you can say WWA is a server that directly consumes and produces messages without any separate broker.

This is why in this document I believe we need to talk about "types" of servers. Because these 2 different types case the whole confusion in the community about our publish and subscribe operations.

I talked about it in my Onboarding sessions, and also there is an example diagram that can be adopted here -> https://github.com/derberg/Documenting-Event-Driven-Architectures---Workshop-Script/blob/main/scripts/theory.md#eda-setup---simplified (the first one)

---

@thulieblack before you start writing about it, let's make sure that others that were involved here in this PR are ok with my suggestion -> @smoya @fmvilas

[fmvilas]

I completely agree with @derberg suggestion. Let's make sure we don't only represent the broker use case 👍

[thulieblack]

Hie @derberg is this the correct way, I know it isn't ideal yet.

flowchart TD
    a[Client Browser] -.-> b[(server)]
    

flowchart TD
    A[producer]
    A --> a1[channel1]
    A --> a2[channel2]
    subgraph one[broker]
    a1
    a2
    end
    a1 --> B[consumer1]
    a2 --> C[consumer2]

[derberg]

@thulieblack it looks awesome. I think broker diagram is perfect. The other one, you could extend by adding Client Mobile App too, and show arrow not only from client to server but from server to client to, to visualize natural bi-directional communication between these

[thulieblack]

@thulieblack it looks awesome. I think broker diagram is perfect. The other one, you could extend by adding Client Mobile App too, and show arrow not only from client to server but from server to client to, to visualize natural bi-directional communication between these

flowchart TD
    a[Client Browser] --> b[(server)]
      b --> a 
    c[Client Mobile] --> b
    b --> c
    

flowchart TD
    A[producer]
    A --> a1[channel1]
    A --> a2[channel2]
    subgraph one[broker]
    a1
    a2
    end
    a1 --> B[consumer1]
    a2 --> C[consumer2]

@derberg is this what you meant?

Also what is the best way to explain the whole diagram, do you have some suggestions please I'll be grateful.

[derberg]

@thulieblack description always below diagram, best have 2 separate headings/sections, Client and Server and Broker-centric. Always when you describe diagram, use the same names that are in the diagram using "bolding" to highlight the name in text, so it is easier to map with the image.

Also, remember to mix theory with how it looks at AsyncAPI. What I wrote in the previous comment, so for example, when describing broker architecture, mention that in this case, you create 3 asyncapi files, one for producer, one for subscriber1 and one for subscriber2, and that all these files, describe everything related to given application, so asyncapi file for producer describes everything producer-related, except that the info in AsyncAPI Server Object does not have the physical location of the producer, but the broker. Then in the case of client->server, you create AsyncAPI file for server, and then AsyncAPI Server Object holds info also about the physical location of the server. I hope I'm making sense 😓 sorry if not, we can hop on a call if ya want

unless I misunderstood your question, and you are asking to suggest some content?

[thulieblack]

@thulieblack description always below diagram, best have 2 separate headings/sections, Client and Server and Broker-centric. Always when you describe diagram, use the same names that are in the diagram using "bolding" to highlight the name in text, so it is easier to map with the image.

Also, remember to mix theory with how it looks at AsyncAPI. What I wrote in the previous comment, so for example, when describing broker architecture, mention that in this case, you create 3 asyncapi files, one for producer, one for subscriber1 and one for subscriber2, and that all these files, describe everything related to given application, so asyncapi file for producer describes everything producer-related, except that the info in AsyncAPI Server Object does not have the physical location of the producer, but the broker. Then in the case of client->server, you create AsyncAPI file for server, and then AsyncAPI Server Object holds info also about the physical location of the server. I hope I'm making sense 😓 sorry if not, we can hop on a call if ya want

unless I misunderstood your question, and you are asking to suggest some content?

No this is what i needed, let me do the 1st draft

[thulieblack]

Thank you @derberg , welcome back hope you had a good vacation 🎉🎉

[derberg]

@thulieblack thanks so much, holidays were great 😄

I guess we just need a final look from @smoya and @fmvilas that left feedback in the past

[thulieblack]

thanks you so much @smoya, @alequetzalli i think its time for some editorial review 😁😁