Traceable Block Decomposition in Diagram-Design: A Complete Guide

Traceable block decomposition is a semantic pattern in Diagram-Design that assigns stable, citable identifiers to hierarchical system components, enabling audit trails and cross-references through a machine-readable registry.

Traceable block decomposition is one of eight semantic patterns defined in the cathrynlavery/diagram-design repository. According to skills/diagram-design/references/semantic-patterns.md (lines 18-31), this pattern structures system architectures into individually addressable sub-elements, each tagged with persistent metadata that survives refactoring and supports automated compliance checks.

What Is Traceable Block Decomposition?

Traceable block decomposition breaks systems or products into individually citable sub-elements, each identified by a stable ID that can be referenced from documentation, audits, or compliance records. As implemented in cathrynlavery/diagram-design, this pattern requires the Tree visual type to express parent-child hierarchy using elbow connectors, with rendering rules governed by skills/diagram-design/SKILL.md.

The pattern serves as the foundation for generating a side-car registry JSON file that aggregates all block metadata. This registry enables CI checks and documentation generators to validate uniqueness, resolve parent links, and detect cycles across the codebase.

Selection Triggers and Required Primitives

You should select this pattern when you need a stable, addressable identifier for each block (e.g., PAY-001-02). Readers must be able to trace a block to its parent, view its inputs and outputs, and locate the implementing code.

The pattern requires these primitives:

• A dotted ID badge rendered as a chip on the node
• A noun-phrase block name representing a structural element, not an action
• Parent-child hierarchy expressed with the Tree visual type's elbow connector
• Optional short inbound/outbound port-labels displayed only when space permits

Metadata Attributes and the Registry JSON

Every block carries data-block-* attributes embedded in the diagram source. According to skills/diagram-design/references/export-registry.md, the CLI emits the full record to a side-car registry when using the --registry flag.

Required attributes include:

• data-block-id: The stable identifier (e.g., PAY-001-02)
• data-block-parent: Reference to the parent block's ID
• data-block-name: The noun-phrase name

Optional attributes support traceability:

• data-block-input and data-block-output: Port specifications
• data-block-constraint and data-block-assumption: Design metadata
• data-block-impl: Path to implementing code

The resulting diagram.registry.json file contains an array of block objects consumable by validation scripts.

Complexity Budget and Hierarchy Limits

The Tree visual type imposes strict limits that apply unchanged to traceable block decomposition. As documented in the source, structures are limited to:

• Root plus 3 tiers maximum
• ≤ 5 nodes per level
• ≤ 9 nodes total

If your architecture requires more depth, split the model into multiple linked diagrams, each independently traceable. The diagram remains static with no animated expansion or filtering; all IDs, names, and port-labels must remain legible in a single rendered frame.

Common Anti-Patterns to Avoid

The semantic-patterns.md file identifies specific anti-patterns that violate traceable block decomposition principles:

• Verb-phrase block names: Names describing actions belong to Flowchart or Swimlane patterns, not this structural decomposition
• Connector labels for IDs: IDs must reside on the node itself via the dotted badge, not on connecting lines
• Four-sided ICOM boxes: This style indicates IDEF0 functional decomposition, which is distinct from traceable block decomposition

When to Use Traceable Block Decomposition

Deploy this pattern when your architecture requires citable components at the block level. Ideal scenarios include:

• Compliance and audit trails: When regulators require stable references to specific system components
• IP tracking: When tracing intellectual property or licensing across modular architectures
• Programmatic queries: When tools need a single source of truth for block identifiers via the registry JSON
• Hierarchical decomposition: When the structure fits within the Tree visual type's node budget

Do not use this pattern for process flows, data-flow pipelines, or IDEF0-style functional decomposition. These scenarios belong to other semantic patterns such as Flowchart or Swimlane.

Implementing Traceable Block Decomposition

Declaring Blocks in Mermaid Syntax

Diagram-Design consumes Mermaid format with embedded data-block-* attributes. The following example shows the correct syntax:

graph TD
    A[data-block-id="PAY-001-02" data-block-name="Fraud Screening"]
    B[data-block-id="PAY-001-03" data-block-name="Risk Scoring"]
    A --> B

The elbow connector (-->) represents the standard Tree edge. No extra connector labels are added; the ID badge renders as a chip on the node itself.

Generating the Registry with the CLI

Generate the machine-readable registry using the --registry flag documented in README.md (lines 381-517):

diagram-design --registry diagram.registry.json input.mermaid

This produces diagram.registry.json containing the full block metadata array, including parent references and optional implementation paths.

Validating Blocks in CI/CD

The repository includes scripts/verify-block-registry.py to enforce pattern constraints during automated testing. The script validates:

#!/usr/bin/env python3
import json, sys, pathlib

registry_path = pathlib.Path(sys.argv[1])
registry = json.loads(registry_path.read_text())

ids = {b["data-block-id"] for b in registry}
if len(ids) != len(registry):
    sys.exit("Duplicate data-block-id found")

# Additional checks for missing parents, cycles, etc.

This validation ensures unique IDs, valid parent links, and acyclic hierarchies before deployment.

Consuming the Registry in Downstream Tools

The registry JSON enables cross-referencing between diagrams and implementation artifacts:

import json

with open("diagram.registry.json") as f:
    registry = json.load(f)

for block in registry:
    if "data-block-impl" in block:
        url = f"https://github.com/example/repo/blob/main/{block['data-block-impl']}"
        print(f"{block['data-block-id']} → {url}")

This mapping connects stable IDs to source code, enabling traceability across the entire codebase.

Summary

• Traceable block decomposition is one of eight semantic patterns in Diagram-Design, defined in semantic-patterns.md, for creating citable, hierarchical system components
• Each block requires data-block-id, data-block-parent, and data-block-name attributes, with optional metadata for inputs, outputs, and implementation references
• The pattern imposes strict complexity limits: root plus 3 tiers, maximum 5 nodes per level, and 9 nodes total
• Use the --registry CLI flag to generate diagram.registry.json for automated validation via verify-block-registry.py
• Apply this pattern for compliance, audit trails, and IP tracking; avoid it for process flows or IDEF0-style functional decomposition

Frequently Asked Questions

How does traceable block decomposition differ from IDEF0?

Traceable block decomposition uses noun-phrase names and dotted ID badges on nodes within a Tree visual type, while IDEF0 uses four-sided ICOM boxes and focuses on functional decomposition with controls, mechanisms, inputs, and outputs. The patterns serve different architectural documentation needs.

What is the maximum number of blocks allowed in a single diagram?

The Tree visual type limits diagrams to a root plus 3 tiers, with a maximum of 5 nodes per level and 9 nodes total. If your architecture exceeds these limits, split the model into multiple linked diagrams, each maintaining independent traceability.

How do I validate block IDs in CI/CD pipelines?

Use the verify-block-registry.py script located in the scripts/ directory. This tool checks for duplicate data-block-id values, missing parent references, and cyclic dependencies in the diagram.registry.json file generated by the --registry flag.

Can I use animated diagrams with this pattern?

No. Traceable block decomposition produces static diagrams only. All IDs, names, and optional port-labels must remain legible in a single rendered frame without animation, expansion, or filtering interactions.

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