# How the Traceable Block Decomposition Pattern Works in Diagram Design

> Explore the traceable block decomposition pattern to model systems as hierarchical blocks. Learn how stable identifiers and data attributes link diagrams to code for precise traceability.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

This command generates [`example.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/example.registry.json) containing the complete hierarchy:

```json
{
  "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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py) (referenced in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) lines 517-522) to enforce block integrity in continuous integration:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/export-registry.md).
- Validation through [`verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.