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

> Learn how the diagram-design agent routes diagram types by parsing tokens validating against a whitelist and dispatching to dedicated parsers for efficient handling.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py). This whitelist acts as a gatekeeper:

```python

# 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:

```python

# 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.

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) produce an intermediate `Diagram` object. Rendering to final output formats occurs downstream, consuming the normalized structure produced after `_finalize_degrees` completes.