# Semantic Patterns in diagram-design: A Complete Guide to the 7 System Behaviors Defined in semantic-patterns.md

> Explore the 7 semantic patterns in diagram-design.md to model system behavior, apply visual grammars, and avoid anti-patterns. Learn best practices for effective system design.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: complete-guide
- Published: 2026-08-21

---

**The [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) file in the cathrynlavery/diagram-design repository defines seven concrete semantic patterns that model system behavior, routing each to an optimal visual grammar while enforcing complexity budgets and anti-pattern avoidance.**

The cathrynlavery/diagram-design repository provides a disciplined framework for technical diagramming that separates *what* a system does from *how* it is visualized. At the core of this approach lies [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), a reference document located at [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) that codifies seven recurring behavioral patterns found in software architecture. These patterns serve as the bridge between conceptual system modeling and concrete visual representation.

## What Are Semantic Patterns?

**Semantic patterns** describe the behavioral intent of a system—what it does—rather than its visual layout. According to the diagram-design source code, these patterns guide the selection of appropriate visual types (the "how") and provide a disciplined vocabulary for modeling behavior, state, enforcement, and risk. Each pattern includes **selection triggers** that determine when to apply it, **required primitives** for minimal visual elements, and **complexity budgets** that limit sources, slots, and layers to maintain readability.

## The Two-Section Architecture of semantic-patterns.md

The document organizes its guidance into two distinct sections that work together to transform system behavior into visual grammar.

### Routing Table

The **routing table** maps each semantic pattern to its nearest visual type, helping authors choose an appropriate diagram grammar without premature commitment to a specific layout. This table serves as the decision layer that translates behavioral intent into visual capability.

### Individual Semantic Pattern Definitions

Each of the seven patterns includes a standardized structure:

- **Selection triggers** – Conditions indicating when the pattern should be applied
- **Required primitives** – The minimal visual elements needed for valid representation
- **Complexity budget** – Constraints on sources, slots, layers, and other dimensions
- **Anti-patterns** – Common pitfalls to avoid during implementation
- **Static fallback** – Rendering strategy when animation or interactivity is unavailable
- **Nearest visual type** – The default visual grammar (e.g., Data flow, Process, Architecture)

## The Seven Semantic Patterns Defined in diagram-design

The [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) file defines seven concrete patterns, each addressing a distinct system behavior:

### 1. Fan-in Queue / Bottleneck

**Core idea:** Multiple producers converge on a constrained resource, requiring focus on arrival rate, queue depth, and back-pressure. This pattern captures throttling and congestion scenarios.

**Nearest visual type:** Data flow (or Process when stages dominate)

### 2. Stage Framework with Semantic Slots

**Core idea:** A repeated lifecycle or operating-model traverses ordered stages (e.g., Question → Input → Governance → Output). This pattern enforces consistency across process phases.

**Nearest visual type:** Process (or Swimlane for owner-centric rows)

### 3. Unstructured Input → Structured Artifact

**Core idea:** Raw dialogue or notes normalize into a durable artifact (ticket, schema, etc.). This pattern bridges informal input and formal system state.

**Nearest visual type:** Data flow (or Process when multiple ordered gates exist)

### 4. Paired Policy-Evaluation Traces

**Core idea:** Two similar requests produce divergent outcomes; tracing rule-by-rule status highlights the first divergence point. Essential for debugging policy engines.

**Nearest visual type:** Flowchart (or Sequence if temporal messaging matters)

### 5. Secure Paved Road

**Core idea:** A bounded route from intake to deployment showing trust boundaries, permitted/forbidden ingress, and privileged gates. This pattern visualizes secure delivery pipelines.

**Nearest visual type:** Architecture

### 6. Governance / Control Catalog

**Core idea:** A catalog of controls grouped by enforcement surface (authoring, CI, runtime, etc.). This pattern organizes compliance and security controls.

**Nearest visual type:** Layer stack (or DP security matrix for role-based comparisons)

### 7. Compensating Security Layers

**Core idea:** Ordered defenses where each layer mitigates weaknesses of the previous layer, visualizing residual risk. This pattern illustrates defense-in-depth strategies.

**Nearest visual type:** Layer stack (or Nested when containment boundaries are key)

## Implementing Semantic Patterns in Practice

These patterns are complemented by **Composition rules** that dictate how a pattern may specialize primitives, enforce budgets, and handle optional animation as defined in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md). Below are minimal Markdown snippets illustrating how to invoke these patterns in a diagram-design document.

### Fan-in Queue Pattern Implementation

```markdown
<!-- Fan-in queue / bottleneck -->
![[type-data-flow]]
source A -->|8/hour| queue Q
source B -->|5/hour| queue Q
queue Q -->|capacity 10| service S
service S --> outcome success
service S --> outcome reject

```

This snippet references [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) to visualize producer convergence and capacity constraints.

### Stage Framework Pattern Implementation

```markdown
<!-- Stage framework with semantic slots -->
![[type-process]]
| Stage | Question | Input | Governance | Output |
|-------|----------|-------|------------|--------|
| 1     | What?   | Data | Review     | Report |
| 2     | Why?    | N/A  | Approve    | Action |

```

This example leverages [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md) to model ordered lifecycle stages with consistent semantic slots.

### Secure Paved Road Pattern Implementation

```markdown
<!-- Secure paved road -->
![[type-architecture]]
trustzone "User Zone" {
  actor User -->|allowed| service FrontEnd
}
trustzone "Secure Zone" {
  actor CI -->|deploy| service Backend
}

```

This implementation uses [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) to render trust boundaries and deployment constraints.

## Summary

- **[`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)** defines seven behavioral patterns that describe *what* systems do before determining *how* to visualize them.
- The **routing table** maps each pattern to its nearest visual type (Data flow, Process, Architecture, Flowchart, Layer stack).
- Each pattern specification includes **selection triggers**, **complexity budgets**, and **anti-patterns** to maintain diagram integrity.
- The patterns cover critical system behaviors: **Fan-in queues**, **Stage frameworks**, **Input normalization**, **Policy evaluation**, **Secure paved roads**, **Governance catalogs**, and **Compensating security layers**.
- Visual type definitions in files like [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md), [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md), and [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) provide the rendering grammar for these semantic patterns.

## Frequently Asked Questions

### What is the purpose of the routing table in semantic-patterns.md?

The routing table serves as a decision matrix that maps each semantic pattern to its optimal visual type. According to the diagram-design source code, this table helps authors select appropriate diagram grammar by matching behavioral intent (the "what") to layout capability (the "how"), preventing premature visualization choices that might obscure system meaning.

### How do complexity budgets prevent diagram anti-patterns?

**Complexity budgets** enforce limits on sources, slots, layers, and other visual dimensions to keep diagrams readable. As defined in the individual pattern specifications within [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), these budgets prevent visual overload by constraining the number of elements that can appear in a single diagram, directly addressing common anti-patterns like "spaghetti diagrams" or information overload.

### What is the difference between a semantic pattern and a visual type?

**Semantic patterns** describe system behavior and intent (e.g., "Fan-in queue" or "Secure paved road"), while **visual types** define the rendering grammar (e.g., Data flow, Architecture). The [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) file handles the behavioral modeling layer, whereas files like [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) and [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) in the same directory handle the presentation layer. The routing table connects these two layers.

### Where are the visual type definitions located in the diagram-design repository?

The visual type definitions reside in the `skills/diagram-design/references/` directory alongside [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md). Specific files include [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) for flow-based diagrams, [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md) for stage-based visualization, [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) for structural diagrams, and [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) for optional animation support. These files provide the concrete grammar that semantic patterns reference through the routing table.