# Understanding Complexity Budgets for Different Diagram Types in diagram-design

> Discover complexity budgets for diagram-design diagrams. Learn about drawable node and edge limits, plus parsing caps for nodes, edges, and file size. Optimize your diagrams now.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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**:

```python

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

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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):

```python
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**:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py).

The `_read_bounded()` function implements this validation:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_input.py))
- **File size protection**: Raw source files cannot exceed 4 MiB, enforced by `_read_bounded()` in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.