Traceable Block Decomposition Pattern: Creating Traceable Diagrams in diagram-design

The traceable block decomposition pattern is a semantic diagram pattern that renders hierarchical structures as static tree diagrams where every block carries a stable identifier (data-block-id) and metadata attributes, enabling auditors and compliance tools to cite and trace each element back to its implementation.

This pattern is one of eight semantic patterns defined in the cathrynlavery/diagram-design skill set. It provides a disciplined approach to breaking systems into individually addressable sub-elements while maintaining strict validation rules and machine-readable metadata.

When to Use the Traceable Block Decomposition Pattern

Use this pattern when each block in your diagram requires a stable identifier that auditors, compliance tools, or developers can reference directly—not merely a human-readable name. It is specifically designed for scenarios where traceability to implementation is mandatory, such as regulatory documentation or safety-critical system architecture.

The pattern applies when you need to depict hierarchical decomposition where parent-child relationships are unambiguous and every element can be cited unambiguously in external documentation.

Visual Structure and Primitives

Tree Diagram Rendering

The traceable block decomposition pattern is always rendered as a Tree diagram. The visualization uses the tree’s elbow connectors to provide the hierarchical layout without adding extra connector semantics. According to the source specification in skills/diagram-design/references/semantic-patterns.md (lines 18-30), no additional connector types are introduced beyond the parent-child hierarchy.

The pattern is strictly static; it does not support animation or dynamic expansion. All identifiers, names, and optional port labels must remain legible in a single rendered frame.

Core Primitives

Every node in the diagram must implement these primitives:

• data-block-id badge: A stable identifier (e.g., PAY-001-02) displayed as a node-box tag
• data-block-name: The noun-phrase describing the structural element (verbs are reserved for flowchart patterns)
• Optional port-label pairs: Inbound/outbound labels displayed only when space permits without crowding
• Metadata attributes: HTML data-block-* attributes carrying id, parent, name, input, output, constraint, assumption, and impl values

Metadata and Registry Export

All block metadata lives within the HTML element’s data-block-* attributes. No visible diagram text duplicates this data, ensuring the visual remains clean while the markup remains machine-readable.

To extract this metadata, the tool supports a --registry flag that emits a .registry.json side-car file. As documented in skills/diagram-design/references/export-registry.md, this file is not a source of truth but a direct JSON projection of the HTML attributes. Generate the registry using:

python3 scripts/render-canonical-screenshots.py \
    assets/example-tree-block-decomposition.html \
    --registry

Constraints and Validation

The pattern enforces strict structural constraints to maintain diagram clarity and traceability:

• Tree limits: Root plus 3 tiers maximum, ≤5 nodes per level, and ≤9 nodes globally
• Single parent: Each block references exactly one parent via data-block-parent
• No cycles: Hierarchical relationships must be acyclic
• Identifier integrity: No duplicate IDs, blank IDs, or blank names allowed

The scripts/verify-block-registry.py script validates these constraints independently of the export step. Run it to check for blank IDs, duplicates, orphan parents, missing names, or cycles:

python3 scripts/verify-block-registry.py --all

Anti-Patterns to Avoid

Avoid these common violations when implementing the traceable block decomposition pattern:

• ICOM boxes: Four-sided IDEF0 boxes introduce extra connector semantics that belong to different patterns
• Sibling arrows: Adding input/output arrows between siblings violates the tree structure; use a dependency-graph pattern instead
• Verb naming: Naming blocks with verbs (actions) confuses this structural pattern with flowchart or swimlane patterns
• Missing badges: Omitting or mismatching data-block-id badges breaks the traceability contract

Implementation Examples

Minimal HTML Structure

The following HTML from skills/diagram-design/assets/example-tree-block-decomposition.html demonstrates the required markup:

<div class="tree">
  <div class="node"
       data-block-id="SYS-001"
       data-block-name="Payment System">
    Payment System
  </div>

  <div class="node"
       data-block-id="SYS-001-01"
       data-block-parent="SYS-001"
       data-block-name="Authorization Service">
    Authorization Service
  </div>

  <div class="node"
       data-block-id="SYS-001-02"
       data-block-parent="SYS-001"
       data-block-name="Settlement Engine">
    Settlement Engine
  </div>
</div>

Each node carries the required data-block-id and data-block-name; children reference their parent via data-block-parent.

Generating the Registry

Export the machine-readable metadata alongside your diagram:

python3 scripts/render-canonical-screenshots.py \
    assets/example-tree-block-decomposition.html \
    --registry

This produces example-tree-block-decomposition.registry.json containing the JSON schema defined in skills/diagram-design/references/export-registry.md.

Validating the Diagram

Verify structural integrity across all shipped assets:

python3 scripts/verify-block-registry.py --all

This reports any blank IDs, duplicates, orphan parents, missing names, or cycles that would compromise traceability.

Summary

• The traceable block decomposition pattern creates hierarchical tree diagrams where every block has a stable, citeable identifier
• Metadata lives exclusively in HTML data-block-* attributes, with optional JSON export via the --registry flag
• Strict constraints apply: maximum 9 nodes, single parent rule, no cycles, and mandatory ID/name fields
• Avoid ICOM boxes, sibling connectors, verb naming, and missing badges to prevent anti-patterns
• Validation is performed by scripts/verify-block-registry.py, ensuring diagram integrity before publication

Frequently Asked Questions

What is the difference between traceable block decomposition and regular tree diagrams?

Regular tree diagrams focus purely on visual hierarchy, whereas the traceable block decomposition pattern requires every node to carry machine-readable metadata via data-block-id and related attributes. This enables automated tools in the cathrynlavery/diagram-design repository to validate references, export registries, and verify that no orphan nodes or cycles exist.

How do I validate that my diagram follows the traceable block decomposition pattern?

Run python3 scripts/verify-block-registry.py --all to check for blank IDs, duplicate identifiers, orphan parents, missing names, and cyclic references. The script operates independently of the rendering process and validates the structural rules defined in skills/diagram-design/references/semantic-patterns.md.

Can I add dynamic animations or expandable nodes to a traceable block decomposition diagram?

No. The pattern is strictly static and does not support animation or dynamic expansion. All identifiers, names, and optional port labels must be legible in a single rendered frame to ensure stable citation and traceability in printed or archived documentation.

What file format does the block registry export use?

The --registry flag generates a .registry.json side-car file containing a JSON projection of all data-block-* attributes. The schema is documented in skills/diagram-design/references/export-registry.md, and the file serves as a machine-readable convenience rather than a source of truth.

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