Show HN: Generate System Design diagrams from design spec (opens in new tab)

(fizzbee.io)

4 pointsjayaprabhakar1y ago2 comments

When designing a distributed system, creating and maintaining design documents with diagrams is time-consuming. FizzBee, our formal methods system, simplifies this process by generating a variety of essential diagrams from a concise, Python-like specification.

FizzBee automatically checks your design for correctness and generates:

- Communication/Block Diagrams: Visualize the components and their interactions.

- State Diagrams: Show all possible system states and transitions.

- Sequence Diagrams: Explore how the system works interactively.

- System Trace Diagrams: Visualize detailed algorithm traces.

All this with less than 100 lines of code.

Here’s a snippet of how simple it is to model a two-phase commit:

```

  action Write:
    if self.state != "init":
      return
    self.state = "working"
    for rm in self.PARTICIPANTS:
      vote = rm.Prepare()

      if vote == 'aborted':
        self.Abort()
        return

      self.prepared.add(rm.ID)
    
    self.Commit()

```

Try it out and see more examples at https://fizzbee.io/tutorials/visualizations/.

Appreciate your feedback.

2 comments

jackdaniels4me1y ago

This is neat! How does this compare with tools like draw.io or mermaidjs

jayaprabhakarOP1y ago

Those are pure drawing tools.

*Tools like draw.io, Lucidchart, and Excalidraw excel at creating raw diagrams through drag-and-drop interfaces. However, they often become cumbersome when updates are needed, and their outputs are rarely stored in source control, making versioning and collaboration more difficult. While these tools give you full control over the layout and appearance of the diagrams, they require manual effort each time you make changes.

*Mermaid.js, websequencediagrams, and PlantUML, on the other hand, allow you to generate diagrams from a text description. FizzBee builds on this concept by generating these text descriptions directly from your algorithm specification, then leveraging mermaid.js to render sequence diagrams and Graphviz for other diagram types.

*Where FizzBee truly shines is in its ability to automatically generate diagrams for every significant scenario your system might encounter, not just a single use case. For example, with a two-phase commit protocol:

- The 'happy path' where all participants and the coordinator agree to commit, and everything proceeds smoothly.

- A case where the first participant prepares, but the second one aborts.

- Scenarios where both participants prepare but some messages get dropped.

- A situation where both participants prepare, but the coordinator crashes and restarts—how does the system recover?

These are just a few examples. The ability to generate these scenarios automatically means FizzBee pays for itself very quickly compared to manually drawing sequence diagrams for each possible case.

This is in addition to verifying for correctness or clearer communication benefits.

j / k navigate · click thread line to collapse