Auto-Generated Flow Diagrams: Visualize Your Demo Steps

Why Diagrams Matter

When presenting a multi-step API workflow, viewers often lose track of where they are in the process. A flow diagram provides context: which step are we on? What comes next? How do the pieces connect?

DemoScript's diagram feature renders animated flow diagrams that highlight the current step and fade completed steps. The diagram stays synchronized with your demo, giving viewers a visual anchor as you progress through each step.

Two Diagram Types

DemoScript supports two diagram types, automatically detected from your configuration:

Flowcharts

Best for showing process flows and decision points. Rendered using React Flow for smooth animations and interactivity. Nodes can represent API endpoints, services, or abstract concepts.

settings:
  diagram:
    enabled: true
    type: flowchart     # Optional, auto-detected
    direction: LR       # Left-to-right (or TD for top-down)

Sequence Diagrams

Best for showing request/response flows between participants (client, server, database). Rendered using Mermaid with message highlighting.

settings:
  diagram:
    enabled: true
    type: sequence
    participants:
      Client:
        label: "Browser"
      Server:
        label: "API Server"
      DB:
        label: "Database"

Three Configuration Modes

DemoScript provides flexibility in how diagrams are generated, from fully automatic to fully custom:

Mode 1: Fully Automatic

The simplest approach. Just enable diagrams and add diagram: values to your steps:

settings:
  diagram:
    enabled: true

steps:
  - rest: POST /auth/login
    diagram: Client->Auth

  - rest: GET /users
    diagram: Auth->API

  - rest: POST /orders
    diagram: API->Orders

DemoScript generates the Mermaid chart, tracks node connections, and highlights the current edge as you progress through steps.

Mode 2: Defined Nodes

For more control over node appearance, define nodes explicitly:

settings:
  diagram:
    nodes:
      Client:
        label: "Web Client"
        shape: stadium
      Auth:
        label: "Auth Service"
        shape: rounded
      API:
        label: "API Gateway"
        shape: rectangle
      DB:
        label: "Database"
        shape: cylinder

Node shapes include: rectangle (default), rounded, stadium, circle, diamond, and cylinder.

Mode 3: Custom Mermaid Chart

For complete control, provide your own Mermaid chart:

settings:
  diagram:
    chart: |
      flowchart LR
        A[Start] --> B{Decision}
        B -->|Yes| C[Process]
        B -->|No| D[Skip]
        C --> E[End]
        D --> E

Step diagram: values are used only for highlighting — mapping steps to edges in your custom chart.

Position Modes

Diagrams can appear in different positions depending on your demo's needs:

• top — Diagram above the step content, replaces the step navigation
• bottom — Diagram below the step content
• sidebar — Fixed right sidebar (great for TD direction)
• toggle — Floating panel, hidden by default, toggled via button
• auto — Smart default: LR diagrams go to top, TD diagrams go to sidebar

settings:
  diagram:
    enabled: true
    position: sidebar    # Or: top, bottom, toggle, auto

Sequence Diagram Syntax

For sequence diagrams, use the familiar arrow syntax in your step diagram: values:

steps:
  - rest: POST /auth/login
    diagram: Client->>Server: Login request

  - rest: GET /users/$userId
    diagram: Server->>DB: Query user

  - slide: "Response received"
    diagram: DB-->>Server: User data

Arrow types:

• ->> — Solid arrow (synchronous request)
• -->> — Dashed arrow (asynchronous/response)

Step Numbers on Edges

Want to show which step corresponds to which edge? Enable step numbers:

settings:
  diagram:
    enabled: true
    show_step_numbers: true

This adds circled numbers (①②③...) to edge labels, making it easy to map diagram edges to demo steps. Numbers appear as Unicode characters for clean rendering.

Edge Styling

Customize edge appearance per-step:

steps:
  - rest: GET /health
    diagram: Monitor->API
    diagram_label: "Health Check"
    diagram_style: dashed

  - rest: POST /critical
    diagram: API->Core
    diagram_style: thick

Available styles: normal (default), dashed, dotted, thick.

Complete Example

Here's a full demo configuration with a sequence diagram:

title: "E-Commerce Checkout Flow"
description: "Complete order workflow with payment processing"

settings:
  base_url: "https://api.example.com"
  diagram:
    enabled: true
    type: sequence
    position: top
    show_step_numbers: true
    participants:
      Browser:
        label: "Customer"
      API:
        label: "API"
      Payment:
        label: "Stripe"
      DB:
        label: "Database"

steps:
  - rest: POST /cart/checkout
    title: "Initiate Checkout"
    diagram: Browser->>API: Start checkout

  - rest: POST /payments/intent
    title: "Create Payment Intent"
    diagram: API->>Payment: Create intent

  - rest: POST /payments/confirm
    title: "Confirm Payment"
    diagram: Browser->>Payment: Confirm card

  - rest: POST /orders
    title: "Create Order"
    diagram: Payment-->>API: Webhook

  - rest: POST /orders/$orderId/fulfill
    title: "Fulfill Order"
    diagram: API->>DB: Save order

Mermaid in Slides

Beyond the diagram panel, you can also embed Mermaid diagrams directly in slide steps using markdown code blocks:

steps:
  - slide: |
      # Architecture Overview

      Here's how our services connect:

      ```mermaid
      flowchart TD
        A[Load Balancer] --> B[API Server]
        B --> C[(Database)]
        B --> D[Cache]
      ```

      The load balancer distributes traffic across API instances.

This renders the Mermaid diagram inline within your slide content, perfect for architecture explanations or static visualizations.

Summary

• Enable diagrams with settings.diagram.enabled: true
• Add diagram: values to steps for edge mapping
• Choose between flowcharts (process flows) and sequence diagrams (request/response)
• Three modes: fully automatic, defined nodes, or custom Mermaid chart
• Position modes: top, bottom, sidebar, toggle, or auto
• Optional step numbers with show_step_numbers: true
• Embed Mermaid in slides with ```mermaid code blocks

Flow diagrams transform demos from linear click-throughs into visual stories. Viewers understand context, see the big picture, and follow along more easily.