# Traceable Block Decomposition in Diagram-Design: A Complete Guide

> Learn about traceable block decomposition in Diagram-Design. Assign stable identifiers to components for audit trails and cross-references. Enhance your system design with this semantic pattern.

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

---

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

```mermaid
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`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (lines 381-517):

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

```

This produces [`diagram.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py) to enforce pattern constraints during automated testing. The script validates:

```python
#!/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:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/diagram.registry.json) for automated validation via [`verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.