# The Eight Behavioral Patterns Defined in Diagram Design's semantic-patterns.md

> Explore eight behavioral patterns in Diagram Design's semantic-patterns.md, including fan-in queues and stage frameworks. Learn to separate system semantics from visual layout for standardized documentation.

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

---

**Diagram Design's [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) defines eight core behavioral patterns—encompassing fan-in queues, stage frameworks, policy traces, and hierarchical decomposition—that separate system semantics from visual layout to standardize technical architecture documentation.**

Diagram Design is an open-source methodology maintained in the `cathrynlavery/diagram-design` repository that distinguishes between **what a system does** (behavioral semantics) and **how information is arranged** (visual types). The file [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) establishes eight primary behavioral patterns serving as the semantic foundation for all diagrams, each including selection triggers, required primitives, complexity budgets, anti-patterns, and a designated nearest visual type for rendering.

## Semantic Patterns vs. Visual Types

Diagram Design enforces a strict separation between semantics and layout. Behavioral patterns describe load-bearing concerns like state, enforcement, and risk, while visual types provide the grammar for arranging elements on the canvas. When authoring a diagram, you select the behavioral pattern first to capture the correct semantics, then apply the nearest visual type to handle the presentation layer.

This architectural split ensures that a **secure paved road** pattern always conveys trust boundaries and audit destinations regardless of whether it is rendered as an architecture diagram or adapted to another layout format.

## The Eight Behavioral Patterns

The following patterns are defined in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), each mapped to specific line ranges and nearest visual types.

### 1. Fan-in Queue / Bottleneck

The **fan-in queue** pattern models scenarios where multiple producers converge on a single constrained resource. As documented at line 20 of [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), this pattern captures arrival rates, queue depth, capacity limits, and back-pressure mechanisms.

- **Nearest visual type**: Data flow
- **Key attributes**: Sources, queue slots, bottleneck name, outcomes
- **Use case**: API throttling, review queues, batch processing bottlenecks

### 2. Stage Framework with Semantic Slots

Defined at line 34, the **stage framework** pattern represents repeated lifecycles where identical semantic questions—question, input, governance, and output—appear across multiple stages. This enforces consistency in how multi-stage pipelines are documented.

- **Nearest visual type**: Process
- **Key attributes**: Ordered stage headers, consistent slot grid
- **Use case**: CI/CD pipelines, approval workflows, transformation stages

### 3. Unstructured Input → Structured Artifact

At line 48, this pattern documents the normalization of raw dialogue or notes into durable records such as tickets, schemas, or briefs. It visualizes source utterances, field extraction, transformation logic, and provenance links between source and destination.

- **Nearest visual type**: Data flow
- **Key attributes**: Source utterances, transformation steps, artifact fields
- **Use case**: Ticket creation from chat logs, meeting note processing, schema extraction

### 4. Paired Policy-Evaluation Traces

Documented at line 62, this pattern displays two similar requests that diverge in outcome, enabling rule-by-rule comparison. It highlights the first point of divergence using PASS, FAIL, SKIPPED, and NOT REACHED markers.

- **Nearest visual type**: Flowchart
- **Key attributes**: Dual traces, rule statuses, first divergence point (firstDiv)
- **Use case**: A/B policy testing, compliance checking, authorization debugging

### 5. Secure Paved Road

The **secure paved road** pattern, defined at line 76, maps bounded routes from intake through deployment. It emphasizes trust boundaries, permitted versus forbidden ingress points, privileged gates, and audit destinations.

- **Nearest visual type**: Architecture
- **Key attributes**: Trust zones, allowed/blocked paths, audit trails
- **Use case**: Zero-trust architectures, deployment pipelines, security boundary documentation

### 6. Governance / Control Catalog

At line 90, this pattern inventories controls organized by enforcement surface—including authoring, CI, and runtime phases. It specifies surfaces, control names, enforcement actors, timing, and exceptions.

- **Nearest visual type**: Layer stack
- **Key attributes**: Control surfaces, enforcement actors, timing, exceptions
- **Use case**: Compliance frameworks, security control matrices, audit preparation

### 7. Compensating Security Layers

Defined at line 104, this pattern models ordered defenses where each layer reduces residual risk left by predecessors. It shows threat input, per-layer mitigation, and residual-risk propagation through the stack.

- **Nearest visual type**: Layer stack
- **Key attributes**: Threat input, mitigation per layer, residual risk levels
- **Use case**: Defense-in-depth strategies, security architecture reviews, risk assessment

### 8. Traceable Block Decomposition

The final pattern at line 118 provides hierarchical decomposition into individually citable blocks with stable identifiers and metadata. It uses the Tree visual type to store IDs, names, and optional port-labels as node attributes, with metadata referencing [`export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-registry.md).

- **Nearest visual type**: Tree
- **Key attributes**: Block IDs, parent relationships, inputs/outputs
- **Use case**: System architecture decomposition, API hierarchy documentation, component libraries

## Implementing Patterns in Diagram Design

To declare a behavioral pattern in a Diagram Design file, use the `pattern` attribute to select the semantics and the `visual` attribute to specify the layout grammar. The DSL automatically enforces complexity budgets and static fallbacks described in the reference file.

### Fan-in Queue Declaration

```yaml
type: diagram
pattern: fan-in-queue
visual: dataflow
sources:
  - name: API
    label: "8 /hour"
  - name: UI
    label: "5 /hour"
queue:
  slots: 3
  capacity: "10 /hour"
bottleneck:
  name: Review
  outcomes:
    - approved
    - rejected

```

### Stage Framework Declaration

```yaml
type: diagram
pattern: stage-framework
visual: process
stages:
  - name: Ingest
    slots:
      question: "What?"
      input: "Raw data"
      governance: "Validate"
      output: "Normalized"
  - name: Enrich
    slots:
      question: "How?"
      input: "Normalized"
      governance: "Enrich"
      output: "Enriched"

```

### Unstructured to Structured Declaration

```yaml
type: diagram
pattern: unstructured-to-structured
visual: dataflow
source: "User request"
transform: "Parse → Map"
artifact:
  name: Ticket
  fields:
    - id
    - summary
    - priority
provenance:
  - from: "User request"
    to: "summary"

```

### Policy Traces Declaration

```yaml
type: diagram
pattern: policy-traces
visual: flowchart
traces:
  - name: Request-A
    rules:
      - {id: 1, status: PASS}
      - {id: 2, status: FAIL}
  - name: Request-B
    rules:
      - {id: 1, status: PASS}
      - {id: 2, status: PASS}
firstDiv: 2

```

### Secure Paved Road Declaration

```yaml
type: diagram
pattern: secure-paved-road
visual: architecture
zones:
  - name: "Public"
    components: [Ingress, API-Gateway]
  - name: "Trusted"
    components: [App, DB]
paths:
  - from: Ingress
    to: API-Gateway
    allowed: true
  - from: API-Gateway
    to: DB
    allowed: false

```

### Governance Catalog Declaration

```yaml
type: diagram
pattern: governance-catalog
visual: layer-stack
surfaces:
  - name: "Write"
    controls:
      - {name: "Code-review", actor: human, timing: merge}
  - name: "Deploy"
    controls:
      - {name: "Signed-image", actor: platform, timing: run}

```

### Compensating Layers Declaration

```yaml
type: diagram
pattern: compensating-layers
visual: layer-stack
risk: "Data-exfiltration"
layers:
  - name: "WAF"
    mitigation: "Block suspicious payloads"
    residual: "Low"
  - name: "IDS"
    mitigation: "Detect lateral movement"
    residual: "Very low"
finalResidual: "Negligible"

```

### Traceable Decomposition Declaration

```yaml
type: diagram
pattern: traceable-decomposition
visual: tree
blocks:
  - id: PAY-001-02
    name: "Fraud Screening"
    parent: ROOT
    inputs: "Transaction payload"
    outputs: "Fraud flag"

```

## Reference Files and Implementation

The eight behavioral patterns are fully specified in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). Implementation details for block-level metadata in pattern 8 appear in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), while optional animation layers referenced by several patterns are documented in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md). The project's root [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) provides workflow integration guidance for applying these semantic constructs to diagram design tasks.

## Summary

- **Diagram Design** separates behavioral semantics from visual layout through eight defined patterns in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md).
- **Fan-in queue** (line 20) and **unstructured-to-structured** (line 48) both map to Data flow visualizations.
- **Stage framework** (line 34) uses Process layouts, while **policy traces** (line 62) require Flowcharts.
- **Secure paved road** (line 76) targets Architecture diagrams for trust boundary visualization.
- **Governance catalog** (line 90) and **compensating layers** (line 104) share the Layer stack visual type for security and compliance modeling.
- **Traceable block decomposition** (line 118) uses Tree structures with stable identifiers for hierarchical system documentation.

## Frequently Asked Questions

### What distinguishes behavioral patterns from visual types in Diagram Design?

Behavioral patterns capture the semantics of what a system does—such as queue behavior, security enforcement, or policy evaluation—while visual types determine how elements are arranged on the canvas. According to [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), you must select the behavioral pattern first to ensure correct semantic modeling, then choose the nearest visual type for layout.

### Which pattern should I use for documenting security boundaries?

Use the **secure paved road** pattern (defined at line 76) for trust boundaries and deployment routes, or **compensating security layers** (line 104) for defense-in-depth architectures. Both patterns include specific attributes for visualizing allowed paths, blocked ingress, and residual risk propagation.

### How does the traceable block decomposition pattern support system documentation?

The **traceable block decomposition** pattern (line 118) assigns stable identifiers to hierarchical blocks, enabling precise citation and traceability. Each block stores ID, name, parent relationships, and port-labels as node attributes in a Tree visual structure, making it ideal for complex architectures requiring rigorous change tracking and component reuse.

### Where are complexity budgets and anti-patterns defined for these behaviors?

Complexity budgets, anti-patterns, and static fallbacks for all eight behavioral patterns are defined alongside the pattern specifications in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). The Diagram Design DSL enforces these constraints automatically when you declare a `pattern` attribute in your diagram file.