Complexity Budget Limits for Different Diagram Types in diagram-design

The diagram-design tool enforces a uniform complexity budget of 9 drawable nodes and 12 edges across all supported diagram types, with additional parsing safety limits of 2000 nodes and 5000 edges to prevent pathological inputs.

The diagram-design repository by cathrynlavery provides a specialized analysis pipeline for Mermaid diagrams that automatically evaluates complexity constraints. Regardless of whether you are working with flowcharts, sequence diagrams, state diagrams, or ER diagrams, the tool applies consistent complexity budget limits to ensure generated summaries remain concise and the system stays performant.

Understanding the Complexity Budget System

Unlike many diagram analysis tools that apply type-specific constraints, diagram-design uses uniform budget values for all supported diagram kinds. The analyze() function in mermaid_extract.py evaluates four distinct boundaries: source file size, parsing limits, drawable node count, and edge count.

The budget system operates in two phases. First, hard parsing limits protect the tool during ingestion. Second, analysis budgets determine whether a diagram is suitable for summary generation based on visual complexity.

Hard Limits vs. Analysis Budgets

Parsing Safety Limits

Before any budget analysis occurs, the parser enforces absolute maximums to prevent memory exhaustion or runaway processing. In mermaid_input.py, the constants MAX_NODES = 2000 and MAX_EDGES = 5000 define these ceilings【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_input.py#L33-L34】.

When the add_node() or add_edge() methods detect counts exceeding these thresholds, the system aborts immediately:

def add_node(self, ...):
    if len(self.nodes) >= MAX_NODES:
        _fail(f"node limit exceeded (max {MAX_NODES})")

def add_edge(self, ...):
    if len(self.edges) >= MAX_EDGES:
        _fail(f"edge limit exceeded (max {MAX_EDGES})")

These parsing limits are safety mechanisms, not the complexity budgets used for final analysis. They handle pathological inputs containing thousands of elements while the actual budget constraints focus on drawable visual complexity.

Source File Size Cap

The tool enforces a 4 MiB source-size limit when reading Mermaid files. Defined as MAX_SOURCE_BYTES = 4 * 1024 * 1024 in mermaid_extract.py【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py#L32-L33】, this check occurs in the _read_bounded() function:

def _read_bounded(path: Path) -> str:
    data = path.open("rb").read(MAX_SOURCE_BYTES + 1)
    if len(data) > MAX_SOURCE_BYTES:
        _fail(f"source exceeds the {MAX_SOURCE_BYTES // (1024 * 1024)} MiB limit")

The Drawable Complexity Budget

The actual complexity budget applies post-parsing and targets leaf nodes that will be rendered rather than total nodes in the graph structure.

Node Budget: 9 Drawable Nodes

The analysis counts only nodes that will actually be drawn (leaf nodes) against the budget. In mermaid_extract.py, the analyze() function calculates drawable = len(leaves) and flags diagrams exceeding 9 drawable nodes【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py#L1106-L1109】:

drawable = len(leaves)  # leaf nodes that will be drawn

info = {
    ...
    "over_node_budget": drawable > 9,  # > 9 leaves → budget violation

    ...
}

When over_node_budget is set to True, the diagram is marked as too complex for standard summary generation.

Edge Budget: 12 Edges

Similarly, the tool limits connections to 12 edges. The same analyze() function checks the total edge count against this threshold【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py#L1106-L1109】:

info["over_edge_budget"] = len(diagram.edges) > 12

This limit applies uniformly across flowcharts, sequence diagrams, state diagrams, and ER diagrams. The verification logic confirms that motion item budget is 12 as referenced in test harnesses【https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py#L303-L306】.

Implementation Details

The budget evaluation occurs in the analysis phase rather than during parsing. While the MAX_NODES and MAX_EDGES constants prevent tool crashes, the 9-node and 12-edge budgets determine content suitability.

Key implementation locations include:

• Core analysis: skills/diagram-design/scripts/mermaid_extract.py implements the budget checks and overall diagram processing
• Input validation: skills/diagram-design/scripts/mermaid_input.py enforces the parsing limits
• Testing: scripts/verify-motion.py validates the budget logic in automated tests

Summary

• Uniform application: All diagram types (flowchart, sequenceDiagram, stateDiagram-v2, erDiagram) share identical complexity budget limits
• Drawable node limit: 9 leaf nodes maximum (over_node_budget flag triggered beyond this)
• Edge limit: 12 edges maximum (over_edge_budget flag triggered beyond this)
• Source size limit: 4 MiB maximum file size enforced during file reading
• Parsing safeguards: Hard limits of 2000 nodes and 5000 edges prevent processing of pathological inputs
• Primary check location: Budget evaluation occurs in analyze() within mermaid_extract.py

Frequently Asked Questions

What happens if a diagram exceeds the 9-node or 12-edge budget?

The analysis marks the diagram with over_node_budget: true or over_edge_budget: true but does not abort processing. The tool continues analyzing the diagram for other metrics, but these flags indicate the diagram exceeds recommended complexity for automatic summary generation.

Are the complexity budgets different for ER diagrams versus sequence diagrams?

No. According to the source code implementation, all diagram kinds share the same budget values. Whether parsing a flowchart, sequence diagram, state diagram, or ER diagram, the analyze() function applies the identical thresholds of 9 drawable nodes and 12 edges.

What is the difference between MAX_NODES and the node budget?

MAX_NODES = 2000 is a parsing safety limit enforced in mermaid_input.py that aborts processing if the total node count (including non-drawable container nodes) exceeds 2000. The node budget of 9 refers only to drawable leaf nodes checked in analyze() after parsing completes. The former prevents crashes; the latter measures visual complexity.

How can I check if my diagram is within budget before running the full analysis?

While the tool does not provide a standalone budget checker, you can examine your Mermaid source for leaf node count. Any diagram with more than 9 elements that will be visibly rendered (excluding grouping containers or defining syntax) will trigger the over_node_budget flag when processed through mermaid_extract.py.

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