Understanding Complexity Budgets for Different Diagram Types in diagram-design

The diagram-design repository enforces uniform complexity budgets of 9 drawable nodes and 12 edges across all supported diagram types, alongside hard parsing limits of 2000 nodes, 5000 edges, and a 4 MiB source file cap.

The cathrynlavery/diagram-design project implements strict complexity controls to ensure generated diagram summaries remain concise and performant. Unlike tools with type-specific restrictions, this system applies consistent node and edge limits to flowcharts, sequence diagrams, state diagrams, and ER diagrams through a unified analysis pipeline.

Uniform Complexity Budgets Across All Diagram Types

Diagram-design treats flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram identically when evaluating complexity. The system monitors two primary budget metrics in the analyze() function within skills/diagram-design/scripts/mermaid_extract.py at lines 1106-1109.

Drawable Node Limit

The tool counts leaf nodes—elements that will actually be rendered—and enforces a strict limit of 9 nodes:

# In mermaid_extract.py, analyze() function

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

info = {
    ...
    "over_node_budget": drawable > 9,  # True if exceeds 9 nodes

    ...
}

When over_node_budget evaluates to True, the analysis marks the diagram as exceeding its visual complexity allocation.

Edge Connection Limit

Similarly, the system evaluates relationship complexity against a 12-edge limit:

# In mermaid_extract.py, analyze() function

info = {
    ...
    "over_edge_budget": len(diagram.edges) > 12,  # True if exceeds 12 edges

    ...
}

These checks occur after parsing completes, ensuring the final diagram structure meets the tool's conciseness standards regardless of diagram type.

Hard Parsing Limits vs. Complexity Budgets

While the 9-node and 12-edge budgets govern final output quality, diagram-design implements significantly higher protective boundaries during the parsing phase. These limits prevent resource exhaustion when processing pathological inputs and are defined in skills/diagram-design/scripts/mermaid_input.py at lines 33-34.

Parsing Node Limits

The parser enforces a MAX_NODES constant of 2000 total nodes (including non-drawable elements):

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

This boundary protects the tool from memory exhaustion while processing malformed Mermaid definitions.

Parsing Edge Limits

Similarly, MAX_EDGES is set to 5000:

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

These parsing thresholds do not influence the final complexity budget evaluation but ensure the tool remains stable on atypical inputs.

Source File Size Constraints

Before parsing begins, diagram-design validates raw input file dimensions. The constant MAX_SOURCE_BYTES = 4 * 1024 * 1024 (4 MiB) is defined at lines 32-33 of mermaid_extract.py.

The _read_bounded() function implements this validation:

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")

This guard prevents the tool from attempting to process oversized Mermaid definition files that would degrade performance.

Summary

• Uniform application: All diagram types share identical complexity budgets of 9 drawable nodes and 12 edges
• Implementation location: Budget checks occur in analyze() within skills/diagram-design/scripts/mermaid_extract.py (lines 1106-1109)
• Parsing safeguards: Hard limits of 2000 nodes and 5000 edges prevent resource exhaustion during initial parsing (mermaid_input.py)
• File size protection: Raw source files cannot exceed 4 MiB, enforced by _read_bounded() in mermaid_extract.py
• Violation detection: Exceeding budgets sets over_node_budget or over_edge_budget flags in the analysis result dictionary

Frequently Asked Questions

Do flowcharts have different complexity budgets than sequence diagrams?

No. The diagram-design tool applies uniform complexity budgets across all supported diagram types including flowcharts, sequenceDiagram, stateDiagram-v2, and erDiagram. All types are subject to the same 9 drawable node and 12 edge limits, as implemented in the analyze() function that processes the parsed diagram structure regardless of its original syntax.

What happens when a diagram exceeds the complexity budget?

When the drawable node count exceeds 9 or the edge count exceeds 12, the analysis marks the diagram with over_node_budget or over_edge_budget boolean flags set to True in the info dictionary. These flags indicate the diagram violates the complexity constraints designed to keep generated summaries concise, though the tool typically continues processing rather than failing entirely.

Why does diagram-design have both budget limits and parsing limits?

The complexity budgets (9 nodes, 12 edges) ensure output quality and readability for the final diagram summary, preventing overly dense visualizations. The parsing limits (2000 nodes, 5000 edges) serve as protective infrastructure boundaries to prevent memory exhaustion or crashes when encountering pathological input files. The parsing thresholds are significantly higher because they count all nodes including non-drawable intermediate elements, while budgets apply only to renderable leaf nodes.

How can I check if my diagram source file is too large?

The tool automatically validates file size when reading input through the _read_bounded() function in skills/diagram-design/scripts/mermaid_extract.py. If your Mermaid source exceeds 4 MiB (MAX_SOURCE_BYTES), the tool raises a failure immediately before parsing begins, alerting you that the source exceeds the 4 MiB limit and terminating processing to prevent performance degradation.

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