narwhal icon indicating copy to clipboard operation
narwhal copied to clipboard

[doc] Update the primary and worker diagrams

Open huitseeker opened this issue 4 years ago • 8 comments

Story

We have inserted new components to our primary as part of e.g.#125 and #130 (block synchronizer, subscriber).

We should update the diagrams in https://github.com/MystenLabs/narwhal/tree/main/.assets in order to reflect those changes.

We could:

  • keep the existing draw.io approach,
  • or translate those diagrams to Mermaid for easier maintenance.

huitseeker avatar Apr 27 '22 12:04 huitseeker

/cc @akichidis @asonnino @Clay-Mysten

huitseeker avatar Apr 27 '22 12:04 huitseeker

I have no experience with Mermaid but it seems cool and have no objection to either approaches

asonnino avatar Apr 27 '22 13:04 asonnino

Thanks @huitseeker for keeping us honest with the docs. I've seen Mermaid getting lot of popularity across the eng community and it's awesome when it comes to maintenance and especially for flow & sequence diagrams. My slight objection is that its capabilities are a bit limited when it comes to designing something other than flow (e.x architecture diagrams in AWS , or something more complex to visualise). I find draw.io superior to that and to be honest the UI really helps. Same with @asonnino , have no objection with either approach - slight preference to draw.io

akichidis avatar Apr 27 '22 13:04 akichidis

Folks, this issue is about the staleness of that specific picture: https://github.com/MystenLabs/narwhal/blob/main/.assets/diagram-primary.svg

Which has grown stale and that we'd like to integrate in our docs. I'll consider the issue closed as soon as the diagram is up to date with the consensus subscriber and the block synchronizer, whatever tooling is used to achieve the result :)

huitseeker avatar Apr 27 '22 13:04 huitseeker