How the diagram-design Agent Handles Routing for Different Diagram Types

The diagram-design agent routes diagram types by parsing the first token in a Mermaid source file, validating it against a SUPPORTED_KINDS whitelist, and dispatching to a dedicated parser function.

The routing system lives in the cathrynlavery/diagram-design repository, specifically within the core extraction script. By separating detection, validation, and type-specific parsing into distinct phases, the agent ensures clean separation of concerns while maintaining extensibility for new diagram formats.

Diagram Type Detection

The routing process begins with token extraction from the Mermaid source. The parser identifies the diagram kind by reading the first meaningful token after the opening declaration.

In skills/diagram-design/scripts/mermaid_extract.py, the code extracts tokens such as:

• graph or flowchart → flowchart diagrams
• sequenceDiagram → sequence diagrams
• stateDiagram → state diagrams
• classDiagram → class diagrams
• erDiagram → entity-relationship diagrams

This detection happens early in the parsing pipeline, allowing the agent to fail fast on unsupported formats before investing computational resources.

The SUPPORTED_KINDS Whitelist

The agent enforces routing discipline through a SUPPORTED_KINDS constant defined at line 330 of mermaid_extract.py. This whitelist acts as a gatekeeper:

# Conceptual guard clause from the routing logic

if token not in SUPPORTED_KINDS:
    raise AssertionError(f"unsupported diagram kind: `{token}`")

Any token absent from SUPPORTED_KINDS triggers an immediate error, preventing ambiguous routing and ensuring predictable behavior. This design choice surfaces unsupported formats clearly to the caller rather than attempting fallback parsing that could produce corrupted output.

Dispatch Table and Parser Selection

Once validated, the token enters a dispatch table that maps each supported kind to its corresponding handler function. The routing core follows this pattern:

# Routing logic structure (derived from mermaid_extract.py implementation)

if token == "graph":
    diagram = Diagram(...)
    _parse_flowchart(diagram, lines, header_position)
elif token == "sequenceDiagram":
    diagram = Diagram(...)
    _parse_sequence(diagram, lines, header_position)
elif token == "stateDiagram":
    diagram = Diagram(...)
    _parse_state(diagram, lines, header_position)

# ... additional diagram types

Key characteristics of this dispatch mechanism:

• Explicit function mapping — each diagram type receives its own _parse_* routine, keeping grammar logic isolated and maintainable
• Consistent interface — all handlers accept the same three parameters: a Diagram instance, the source lines, and the header position
• Fresh Diagram instantiation — every routed call creates a new Diagram object, preventing state leakage between different diagram types

Type-Specific Parser Implementation

The dedicated parsers contain grammar-specific logic for their respective diagram types. For example, the flowchart parser at line 1018 processes directional declarations, node definitions, and edge connections using syntax rules unique to flowchart notation.

# Example: flowchart routing invocation

_parse_flowchart(diagram, lines, header_position)

While the parsing internals differ substantially between diagram types, they share a common output contract: populations of the Diagram object's node and edge collections.

Universal Post-Processing

After type-specific parsing completes, all diagrams undergo _finalize_degrees at line 1031. This common post-processor performs:

• Depth computation for hierarchical layout
• Cycle detection in graph structures
• Edge budget validation
• Generic metadata enrichment

This ensures that regardless of which routing path was taken, the final Diagram object presents a uniform interface to downstream consumers.

Summary

• Token extraction identifies diagram kinds from Mermaid source declarations
• SUPPORTED_KINDS whitelist prevents routing to unimplemented parsers
• Dispatch table maps validated tokens to dedicated _parse_* functions
• Consistent handler interface (diagram, lines, header_position) simplifies extension
• _finalize_degrees applies universal post-processing across all diagram types

Frequently Asked Questions

What happens when the diagram-design agent encounters an unsupported diagram type?

The agent raises an AssertionError with a descriptive message including the unsupported token. This occurs during the validation phase before any type-specific parsing begins, ensuring clean failure without partial state modifications.

How can I add support for a new diagram type in the routing system?

Extend SUPPORTED_KINDS with the new token, implement a corresponding _parse_newtype function following the three-parameter interface, and add the dispatch case to the routing conditional. The modular design isolates changes to a single parser implementation.

Does the routing system support diagram type aliases?

The whitelist-based approach treats tokens literally. Aliases like flowchart versus graph require explicit entries in both SUPPORTED_KINDS and the dispatch table, typically delegating to shared implementation functions where grammar overlaps exist.

Where does the actual diagram rendering occur relative to the routing logic?

Routing and parsing in mermaid_extract.py produce an intermediate Diagram object. Rendering to final output formats occurs downstream, consuming the normalized structure produced after _finalize_degrees completes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}