# Fan-In Queue/Bottleneck Pattern: Diagram Routing and Budget Constraints

> Explore the fan-in queue/bottleneck pattern, learn its default Data flow visual type, and understand its strict budget constraints for efficient diagram routing. Optimize your designs now.

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

---

**The fan-in queue/bottleneck pattern routes to the Data flow visual type by default, switching to Process only when service-stage details dominate, while enforcing a strict complexity budget of no more than five sources, five queue slots, one bottleneck, two outcomes, and nine primary nodes.**

The `cathrynlavery/diagram-design` repository provides semantic routing rules that map architectural patterns to appropriate visual representations. Understanding how the **fan-in queue/bottleneck pattern** translates into diagram syntax ensures your visualizations remain readable while accurately conveying contention and back-pressure dynamics. This specification governs how multiple producers converge on a constrained service point without creating visual chaos.

## Visual Type Routing for Fan-In Queue Patterns

According to [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) (lines 11-13), the **fan-in queue/bottleneck** semantic pattern defaults to the **Data flow** visual type. This routing emphasizes the movement of data through constrained channels and highlights back-pressure scenarios where multiple sources compete for limited processing capacity.

The pattern only switches to the **Process** visual type when service-stage implementation details dominate the representation. This fallback ensures that diagrams highlighting internal service mechanics rather than data movement receive appropriate visualization treatment, though this occurs only when specific service details override the default data-flow semantics.

## Complexity Budget Constraints

The pattern enforces specific limits to maintain readability and visual clarity. As defined in the semantic patterns specification, the **complexity budget** restricts diagrams to the following hard limits:

- **Sources (producers)**: ≤ 5
- **Queue slots (visible positions)**: ≤ 5
- **Bottleneck (constrained service point)**: 1
- **Outcomes (admitted / deferred)**: 2
- **Primary nodes (overall diagram elements)**: ≤ 9

When source counts exceed five, the specification requires aggregation into a named cohort (lines 26-27 of [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)). This aggregation prevents visual clutter while preserving the semantic meaning of multiple producers feeding into the constrained queue.

## Implementation Examples

The repository supports two primary definition formats for declaring fan-in queue diagrams that respect these budget constraints.

### JSON-Style Definition

The CLI and SDK accept definitions using standard JSON structure with explicit budget declarations:

```json
{
  "type": "dataflow",
  "semanticPattern": "fan‑in‑queue",
  "budget": {
    "sources": 3,
    "queueSlots": 4,
    "bottleneck": true,
    "outcomes": 2,
    "primaryNodes": 7
  },
  "nodes": [
    { "id": "src1", "label": "Producer A" },
    { "id": "src2", "label": "Producer B" },
    { "id": "src3", "label": "Producer C" },
    { "id": "queue", "label": "Queue (3 slots)", "shape": "queue" },
    { "id": "service", "label": "Worker Service (capacity 2 /h)" }
  ],
  "edges": [
    { "from": "src1", "to": "queue" },
    { "from": "src2", "to": "queue" },
    { "from": "src3", "to": "queue" },
    { "from": "queue", "to": "service" },
    { "from": "service", "to": "outcome‑accept", "label": "Accepted" },
    { "from": "service", "to": "outcome‑reject", "label": "Deferred" }
  ]
}

```

This JSON respects the complexity budget by limiting sources to three (under the five-source maximum), queue slots to four (under the five-slot limit), and primary nodes to seven (under the nine-node cap).

### Markdown-Style Diagram Syntax

For documentation integration, use the markdown-native format processed by the `export-diagram` command:

```markdown

```diagram
type: dataflow
semanticPattern: fan‑in‑queue
budget:
  sources: 4
  queueSlots: 5
  bottleneck: true
  outcomes: 2
  primaryNodes: 9
nodes:
  - id: src1   label: "API A"
  - id: src2   label: "API B"
  - id: src3   label: "API C"
  - id: src4   label: "API D"
  - id: queue  label: "Ingress Queue (5 slots)" shape: queue
  - id: svc    label: "Rate‑Limited Service (3 /h)"
  - id: ok     label: "Processed"
  - id: nok    label: "Throttled"
edges:
  - from: src1 to: queue
  - from: src2 to: queue
  - from: src3 to: queue
  - from: src4 to: queue
  - from: queue to: svc
  - from: svc to: ok   label: "Accepted"
  - from: svc to: nok  label: "Rejected"

```

```

Running `opencode export-diagram` processes this syntax to generate a **Data flow** diagram that visualizes the fan-in queue while strictly adhering to the declared budget parameters.

## Source Architecture and Key Files

The routing logic and budget constraints reside in specific repository locations that define the pattern's behavior:

- **[`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md)**: Core specification defining the pattern routing to Data flow (lines 11-13) and the aggregation rules for excess sources (lines 26-27)
- **[`skills/diagram-design/assets/example-queue-animated.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-queue-animated.html)**: Interactive demonstration showing the fan-in queue primitive with animated flow visualization
- **[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)**: High-level reference mapping all semantic patterns to their nearest visual types
- **[`skills/diagram-design/references/type-dependency.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-dependency.md)**: Documentation of the fan-in badge syntax used within dependency graph visualizations

These files collectively provide the architectural context governing how the fan-in queue/bottleneck pattern renders across different output formats.

## Summary

- The **fan-in queue/bottleneck pattern** defaults to **Data flow** diagrams, only routing to **Process** when service implementation details dominate the visualization
- Strict **complexity budgets** enforce maximums of five sources, five queue slots, one bottleneck, two outcomes, and nine primary nodes per diagram
- **Source aggregation** into named cohorts is required when producer counts exceed the five-source limit
- Both **JSON definitions** (for programmatic SDK usage) and **Markdown syntax** (for documentation) support full budget declaration and validation
- The pattern specifically visualizes **contention and back-pressure** dynamics in constrained service architectures

## Frequently Asked Questions

### What happens if my fan-in scenario has more than five sources?

You must aggregate excess sources into a named cohort. According to [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) (lines 26-27), individual producer nodes beyond the five-source budget should be grouped under a single cohort label such as "External APIs" or "Microservice Cluster" to maintain visual clarity while indicating multiple inputs feeding the queue.

### Can I force the fan-in queue pattern to render as a Process diagram instead of Data flow?

The pattern only routes to **Process** when service-stage details dominate the representation. As implemented in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) (lines 11-13), the default routing is strictly **Data flow**, and the alternative Process type activates solely when the visualization focuses on internal service mechanics rather than data movement through the bottleneck point.

### What defines the bottleneck constraint in this pattern?

The bottleneck represents exactly **one** constrained service point where resource contention occurs. The budget strictly limits diagrams to a single bottleneck node, which typically represents a rate-limited worker service, database connection pool, or admission control gateway that creates back-pressure and throttling behavior in the system architecture.

### How do I validate that my diagram respects the complexity budget?

Declare your budget parameters explicitly in either the JSON `budget` object or the YAML frontmatter of the Markdown diagram definition. The repository's rendering engine validates these declarations against the actual node counts during the `export-diagram` process, ensuring your fan-in queue visualization adheres to the nine-node primary limit and other constraints defined in the semantic patterns specification.