# Complexity Budget Limits for Different Diagram Types in diagram-design

> Discover complexity budget limits for diagram types in diagram-design. Learn about the 9 node and 12 edge limit and safety parsing limits to optimize your diagrams.

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

---

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

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

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

```

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

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

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) implements the budget checks and overall diagram processing
- **Input validation**: [`skills/diagram-design/scripts/mermaid_input.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_input.py) enforces the parsing limits
- **Testing**: [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py).