How the Traceable Block Decomposition Pattern Works in Diagram Design

The traceable block decomposition pattern models systems as hierarchies of addressable blocks using stable, dotted identifiers and HTML data attributes to enable precise traceability from visual diagrams to implementation code.

The traceable block decomposition pattern is a semantic modeling approach defined in the cathrynlavery/diagram-design repository that structures complex systems into uniquely identifiable, citation-ready components. Unlike process-oriented diagrams, this pattern focuses exclusively on static architectural structure, making it ideal for microservices, compliance-recorded modules, and component hierarchies that require rigorous traceability between documentation and source code.

Core Primitives and Data Attributes

According to skills/diagram-design/references/semantic-patterns.md (lines 22-33), the pattern relies on specific HTML data attributes attached directly to node elements. These attributes store metadata as a metadata side-car without rendering as separate connector labels; the tree’s existing elbow connectors convey parent-child relationships.

Required Identification Fields

Every block must declare two core attributes:

• data-block-id – A dotted, stable identifier (e.g., PAY-001-02) displayed as a compact badge on the node
• data-block-name – The noun-phrase name of the structural element; never use verb phrases as this describes structure, not actions

Hierarchy and Port Specifications

Optional attributes establish tree relationships and interface contracts:

• data-block-parent – References the parent block’s ID to establish the hierarchy using existing elbow connectors rather than explicit arrows
• data-block-input and data-block-output – Short port-label values that appear only when they fit without crowding the node
• data-block-impl – File path reference to the implementation code location
• data-block-constraint and data-block-assumption – Design documentation captured verbatim in the registry

Complexity Budget and Visual Constraints

The pattern inherits strict limits from the Tree visual type as documented in semantic-patterns.md (lines 24-27):

• Root plus maximum 3 tiers
• Maximum 5 nodes per level
• Global maximum of 9 nodes for overview diagrams

If a hierarchy exceeds these limits, it must be split across multiple linked diagrams, each independently traceable with its own registry.

Registry Export and Machine-Readable Metadata

As detailed in skills/diagram-design/references/export-registry.md (lines 1-18), the --registry flag produces a machine-readable JSON file that projects every data-block-* attribute verbatim. This registry serves as the source of truth for block metadata, while the diagram itself remains a bounded visual view.

Export both SVG and the block registry using:

diagram-design export-diagram example.html --svg-only --registry

This command generates example.registry.json containing the complete hierarchy:

{
  "source": "example.html",
  "blocks": [
    {
      "id": "PAY-001",
      "name": "Payment Gateway",
      "output": "Settled transaction record",
      "constraint": "Every transaction reaches exactly one terminal state",
      "impl": "src/payments/gateway/"
    },
    {
      "id": "PAY-001-01",
      "parent": "PAY-001",
      "name": "Card Authorization",
      "input": "Raw card details from checkout",
      "output": "Authorization token or decline",
      "assumption": "Runs behind the PCI-scoped boundary",
      "impl": "src/payments/authorization/"
    }
  ]
}

CI Validation and Integrity Checks

The repository includes scripts/verify-block-registry.py (referenced in README.md lines 517-522) to enforce block integrity in continuous integration:

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

This script validates:

• Duplicate ID detection across the registry
• Missing parent resolution (orphaned child blocks)
• Cycle detection in the hierarchy
• Blank IDs and missing names

Anti-Patterns and Common Mistakes

The documentation in semantic-patterns.md (lines 28-33) identifies specific violations that break the traceable block decomposition contract:

• Using ICOM boxes: Four-sided boxes with inputs/outputs on each side belong to IDEF0, not this pattern
• Sibling dependencies: Adding input/output arrows between sibling blocks indicates a Dependency-graph pattern, not a decomposition hierarchy
• Verb phrase naming: Block names must be noun phrases; actions belong in Flowchart or Swimlane patterns
• ID badge mismatches: Providing a visual ID badge without a matching data-block-id or renaming blocks without updating the registry causes the validator to flag errors

When to Use Traceable Block Decomposition vs. Alternative Patterns

Use traceable block decomposition when a product or service must be broken into stable, uniquely-identified sub-elements (e.g., microservices, compliance-recorded modules) so readers can point to a specific block and locate its code or documentation. This pattern describes structure, not process.

Avoid this pattern for:

• Ordered actions: Use Flowchart or Swimlane patterns instead (as noted in semantic-patterns.md lines 18-33)
• Process flows: The pattern describes static structure, not dynamic behavior
• Dynamic visualizations: The pattern renders only as static diagrams; no animated or interactive expansion is supported, and all badges must be legible in a single rendered frame

Summary

• The traceable block decomposition pattern creates hierarchies of addressable blocks using data-block-id, data-block-name, and data-block-parent attributes stored directly on HTML elements.
• Visual constraints enforce a complexity budget of root plus 3 tiers, maximum 5 nodes per level, and 9 nodes globally.
• The --registry flag exports machine-readable JSON metadata containing all data-block-* attributes as implemented in export-registry.md.
• Validation through verify-block-registry.py ensures ID uniqueness, parent resolution, and absence of cycles.
• This structural pattern contrasts with process-oriented Flowcharts and IDEF0 diagrams and is strictly static with no interactive expansion support.

Frequently Asked Questions

What distinguishes traceable block decomposition from IDEF0 diagrams?

Traceable block decomposition uses tree-structured elbow connectors and HTML data attributes to establish parent-child relationships, while IDEF0 utilizes four-sided ICOM boxes with inputs, outputs, controls, and mechanisms on each side. The traceable pattern focuses on component hierarchy and stable identification via data-block-id badges rather than functional decomposition with control flows.

How do child blocks reference their parents in the hierarchy?

Child nodes include a data-block-parent attribute containing the exact data-block-id value of their parent node. The Tree visual type automatically renders elbow connectors between parents and children without requiring explicit arrow definitions or connector labels in the markup.

What enforcement exists for the complexity budget limits?

While the verify-block-registry.py script validates structural integrity, the primary enforcement of the root-plus-3-tier and 5-nodes-per-level limits occurs during diagram design review. Hierarchies exceeding these bounds must be split into multiple linked diagrams, each maintaining independent traceability through separate registry files generated via the --registry flag.

Can traceable block diagrams include interactive animations or expandable sections?

No. According to semantic-patterns.md (lines 28-33), the pattern always renders as a static diagram. All ID badges, block names, and any shown port labels must be legible in the single rendered frame without animation, expansion, or interactive elements.

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