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

> Learn the traceable block decomposition pattern for creating traceable diagrams. This semantic pattern uses stable identifiers for auditability and compliance, letting you cite and trace each element.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) side-car file. As documented in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-tree-block-decomposition.html) demonstrates the required markup:

```html
<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:

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

```

This produces [`example-tree-block-decomposition.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/example-tree-block-decomposition.registry.json) containing the JSON schema defined in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md).

### Validating the Diagram

Verify structural integrity across all shipped assets:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), and the file serves as a machine-readable convenience rather than a source of truth.