ADR 054: Dependency graph as an in-memory index

Date: 2026-07-15

Status: Accepted

Decision Makers: @derlinne, @luckey

Context

Graph queries (dependencies, dependents) over any artifact type must be fast in real time.

Decision

The dependency graph spans all artifact types, not just Elements. Its edges are the typed references every artifact declares — an Element's $ref (schema-ref), xs:import (xsd-import) and concrete x-core-ref association targets (association-ref), a Mapping's source and target (mapping-source/mapping-target), a Pipeline's node references (pipeline-node), a DataSetDatasetA data-related element that contains processed data and makes it available for consumption. A Dataset is populated via Pipelines and carries Metadata and access permissions.'s members (dataset-ref), a DataStructure's members (datastructure-ref) and a DataSource's/DataSink's bound Element (datasource-element/datasink-element). It is rebuilt at startup from the stored artifact_reference edges across every artifact (listAllUrns()) and kept in memory, updated on every write.

Rationale

• Graph queries must be fast in real time for any artifact type — exactly what the admin UI's graph view renders.
• The in-memory graph is a read cache — reconstructable after a restart from the durable artifact_reference edges the registry persists per write.
• The stored edges are the complete truth (including cycles); the registry holds the full reference graph (ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 056).

See also

• Artifact Relations Graph