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

Diagram Design's 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 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, 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, 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.

• 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

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

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

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

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

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

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

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

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. Implementation details for block-level metadata in pattern 8 appear in skills/diagram-design/references/export-registry.md, while optional animation layers referenced by several patterns are documented in skills/diagram-design/references/animation.md. The project's root 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.
• 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, 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. The Diagram Design DSL enforces these constraints automatically when you declare a pattern attribute in your diagram file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}