# Diagram Types for Structure in Diagram Design: 4 Supported Mermaid Kinds Explained

> Explore four structural diagram types flowchart sequenceDiagram stateDiagram-v2 and erDiagram supported by the Diagram Design library using Mermaid. Learn how to create clear structural diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-08

---

**The Diagram Design library supports four structural diagram types—flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram—based on Mermaid's grammar, as defined in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py).**

When working with the `cathrynlavery/diagram-design` repository, you can create structural visualizations using specific Mermaid diagram grammars recognized by the core parser. The library processes files with extensions `.mmd`, `.mermaid`, or fenced code blocks in Markdown to identify and render these diagram types correctly.

## The Four Supported Diagram Types for Structure

According to the source code in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), the constant `SUPPORTED_KINDS` declares exactly four diagram kinds that the parser recognizes for structural visualizations:

| Diagram Kind | Typical Use Case | Default Direction |
|--------------|------------------|-------------------|
| **flowchart** (also called *graph*) | General-purpose process or hierarchy diagrams | LR (left-to-right) |
| **sequenceDiagram** | Interaction flows between participants | LR |
| **stateDiagram-v2** | Finite-state or state-machine diagrams | TD (top-down) |
| **erDiagram** | Entity-relationship / data-model diagrams | TD |

Each kind is automatically detected by the `detect_kind` helper routine, which matches the leading keyword of a Mermaid block to determine the appropriate parser behavior and default layout direction.

## How Diagram Detection Works in the Source Code

In [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), the parser analyzes the leading keyword of each Mermaid block to classify the diagram. When processing input, the system returns a structured object containing the `kind`, `direction`, and start position, enabling downstream tools to handle validation, rendering, and export operations.

The detection mechanism differentiates between flowcharts (which may be declared as either `flowchart` or `graph`), sequence diagrams, state machines, and entity-relationship models based on the first token of the diagram definition.

## Working with Structural Diagrams

You can interact with these diagram types using either the command-line interface or Python programmatically.

### Command-Line Usage

Import and analyze Mermaid files directly from the terminal:

```bash

# Import a Mermaid file and list the detected diagram types

diagram-design import-mermaid path/to/example.mmd

```

### Python Programmatic Usage

Access the parser directly to analyze diagram structures:

```python
from skills.diagram_design.scripts.mermaid_extract import Diagram, parse_block

# Load a Mermaid snippet

source = """
stateDiagram-v2
    [*] --> Idle
    Idle --> Running
    Running --> [*]
"""

# Create a Diagram object and analyze it

diagram = Diagram(index=0, kind="stateDiagram-v2", source_line=0, direction="TD")
info = parse_block(diagram)
print(info)   # → {'kind': 'stateDiagram‑v2', 'direction': 'TD', ...}

```

### Example Flowchart Syntax

For quick reference, here is valid syntax for the flowchart kind:

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Continue]
    B -->|No| D[Stop]

```

## Summary

- **Four structural types** are supported: flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram, as defined in `SUPPORTED_KINDS`.
- **Detection logic** resides in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) using the `detect_kind` function.
- **Default directions** vary by type: flowcharts and sequence diagrams default to LR (left-to-right), while state and ER diagrams default to TD (top-down).
- **File support** includes `.mmd`, `.mermaid`, and Markdown fenced code blocks.
- **Integration** available via CLI (`diagram-design import-mermaid`) or Python API (`Diagram` class and `parse_block` function).

## Frequently Asked Questions

### What file formats does Diagram Design accept for structural diagrams?

The library processes three input formats: standalone files with `.mmd` or `.mermaid` extensions, and fenced code blocks within Markdown files. The parser in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) automatically detects the diagram kind from the leading keyword regardless of the container format.

### How does the parser determine the direction of a structural diagram?

The `detect_kind` function assigns default directions based on diagram type: flowchart and sequenceDiagram default to LR (left-to-right), while stateDiagram-v2 and erDiagram default to TD (top-down). These defaults are applied when processing the diagram block unless overridden by explicit syntax in the Mermaid source.

### Can I use the 'graph' keyword instead of 'flowchart'?

Yes. The source code recognizes both `flowchart` and `graph` as valid identifiers for the same diagram kind. The `SUPPORTED_KINDS` constant and detection logic in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) treat these keywords equivalently when parsing structural diagrams.

### Where can I find the CLI documentation for importing diagrams?

The command-line documentation is located in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md), while detailed usage guides reside in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md). Both files provide comprehensive instructions for using the `diagram-design import-mermaid` command with the four supported structural diagram types.