# Complexity Budgets for Different Diagram Types in diagram-design: 9 Nodes, 12 Edges, and Source Limits

> Discover complexity budgets for diagram types in diagram-design. Learn about the 9 node and 12 edge limits for flowcharts, sequence diagrams, and more.

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

---

**The diagram-design tool enforces a uniform complexity budget of 9 drawable nodes and 12 edges across all supported diagram types, including flowcharts, sequence diagrams, state diagrams, and ER diagrams.**

The `cathrynlavery/diagram-design` repository provides a Mermaid diagram analysis pipeline that flags overly dense visuals before they are rendered. Understanding the **complexity budgets for different diagram types** helps authors keep their diagrams concise and readable. These budgets are evaluated after parsing in the `analyze()` function inside [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) and apply uniformly regardless of diagram kind.

## Uniform Node and Edge Budgets

All diagram types share the same two complexity budget thresholds. The tool does not differentiate between flowcharts, sequence diagrams, state diagrams, or ER diagrams when checking for visual density.

### Drawable Node Limit (9 Nodes)

In [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), the `analyze()` function calculates how many leaf nodes will actually be drawn. It then sets the budget flag via `info["over_node_budget"] = drawable > 9` at lines 1106–1109. If a diagram contains more than nine rendered nodes, it is marked as **over-node-budget**.

### Edge Limit (12 Edges)

The same `analyze()` function checks the edge count with `info["over_edge_budget"] = len(diagram.edges) > 12`. Any diagram containing more than twelve edges is flagged as **over-edge-budget**. The test harness in [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) at lines 303–306 verifies that this 12-edge limit is enforced correctly.

## Input Safeguards and Hard Parser Limits

The repository distinguishes between user-facing complexity budgets and internal parser guardrails. The latter exist to prevent pathological inputs from crashing the tool.

### Source File Size Cap (4 MiB)

Before parsing begins, the tool rejects oversized raw inputs. The constant `MAX_SOURCE_BYTES = 4 * 1024 * 1024` is defined at lines 32–33 of [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py). The `_read_bounded()` helper reads the file and calls `_fail()` if the source exceeds 4 MiB.

### Parser-Level Node and Edge Ceilings (2000 / 5000)

In [`skills/diagram-design/scripts/mermaid_input.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_input.py), the constants `MAX_NODES = 2000` and `MAX_EDGES = 5000` protect the extraction pipeline. The `add_node()` and `add_edge()` methods abort processing with `_fail()` if these thresholds are reached at lines 33–34. These are hard performance limits, not the final complexity budgets.

## How the Budget Logic Is Implemented

The following snippets from the `cathrynlavery/diagram-design` source show exactly where the limits are applied.

### Final Analysis Checks

After parsing completes, the `analyze()` function evaluates the drawable node count and total edge count:

```python

# In `analyze()` – after the diagram is fully parsed

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

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

    "over_edge_budget": len(diagram.edges) > 12,  # > 12 edges → violation

    ...
}

```

### Parser Hard Limits

The input parser rejects diagrams that exceed its internal capacity:

```python

# Parsing limits – enforced when adding nodes/edges

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

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

```

### Source Size Guard

The file reader prevents excessive memory usage from large source files:

```python

# Source-size guard – applied when reading the input file

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

```

## Summary

- The **complexity budgets for different diagram types** are uniform: 9 drawable nodes and 12 edges.
- Violations are detected in `analyze()` inside [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py).
- Raw source files are capped at **4 MiB** via `MAX_SOURCE_BYTES`.
- Parser-level limits of **2000 nodes** and **5000 edges** prevent abuse but do not override the final readability budget.

## Frequently Asked Questions

### Do complexity budgets vary by diagram type in diagram-design?

No. The tool applies the same 9-node and 12-edge budget to flowcharts, `sequenceDiagram`, `stateDiagram-v2`, and `erDiagram` alike. The `analyze()` function checks these limits after parsing without branching on diagram kind.

### What happens when a diagram exceeds the node or edge budget?

The analysis dictionary sets `"over_node_budget": true` or `"over_edge_budget": true` at lines 1106–1109 of [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py). These flags signal that the diagram is visually dense, but processing continues so the caller can decide how to handle the violation.

### Why does the parser allow 2000 nodes when the budget is only 9?

The `MAX_NODES = 2000` and `MAX_EDGES = 5000` constants in [`skills/diagram-design/scripts/mermaid_input.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_input.py) are hard safety limits to prevent denial-of-service from pathological inputs. The 9-node and 12-edge values are stylistic complexity budgets used in the final analysis to encourage readable diagrams.

### Where is the 4 MiB source-size limit defined?

The limit is defined as `MAX_SOURCE_BYTES = 4 * 1024 * 1024` in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) at lines 32–33. The `_read_bounded()` helper enforces this cap when reading raw Mermaid source files from disk.