Use Case

Currently, when documenting complex Flows in EventCatalog, there is no native way to add contextual descriptions or visually group specific sets of steps directly within the Flow visualization.

Imagine a flow where I have 4 very similar steps (e.g., 4 consecutive API calls to the same external service, or 4 similar validation events), but each is used in a slightly different context or for a different edge case.
Right now, to explain the nuance between them, I have to write a lengthy paragraph in the main Markdown body. This creates a disconnect because the reader has to look back and forth between the text and the generated diagram.

I want to be able to add a "Note" that explicitly targets specific step IDs. The system should then visually indicate this on the Flow diagram (e.g., by drawing a bounding box around those steps with a description, or placing a visible sticky note above them) so the context is immediately clear.

Proposed Solution

Extend the Flow frontmatter schema to include an annotations (or notes) array.

Example configuration:

annotations:
  - title: "Fallback Mechanism"
    description: "These steps are only triggered if the primary payment gateway fails."
    steps: ["step-3", "step-4"] # Applies to these specific steps
  - title: "Legacy Support"
    description: "This step is deprecated and will be removed in v2."
    steps: ["step-5"] # Applies to a single step

In the UI, this could be rendered in a few ways:

• Grouping: If multiple steps are selected, draw a dashed bounding box (Group Node) around them with the title/description at the top.
• Badges/Tooltips: Add an info icon or a small "sticky note" component attached to the specific nodes in the graph.

Implementation Notes

No response

Community Notes

• Please vote by adding a 👍 reaction to the issue to help us prioritize.
• If you are interested to work on this issue, please leave a comment.
• If this issue is labeled needs-discussion, it means the spec has not been finalized yet. Please reach out in the EventCatalog Discord.