Graph URN Taxonomy

This page defines the canonical URN templates used by the CodeRadius graph.

It started as a DataContainer scoping note, but the current architecture is broader: the graph is keyed by URN, so the URN taxonomy is part of the product model, not just an ingestion detail.

If two resources should converge to the same node, they must produce the same URN. If two resources should stay isolated, they must produce different URNs.

Core Rule

All graph identifiers use the cr: scheme:

cr:{type}:{segment1}:{segment2}:...

URNs are built by buildUrn().

Important constraints:

• URNs are forward-only identifiers.
• They must not be parsed with naive split(':') logic.
• Some resource types are lowercased by the builder because their identity is case-insensitive.
• File paths, HTTP paths, PHP Class::method signatures, and scoped package names are stored verbatim.

See src/graph/urn.ts for the normalization and non-reversibility contract.

Namespace Terms

The templates below use these placeholder names:

Canonical URN Templates

Note: the URN type-token doesn't always match the node label. ProjectDirectory is the one exception in this table (URN prefix stays directory).

The Four Most Important Templates

For the current taxonomy work, these are the key identities:

cr:function:{qualifiedRepo}:{language}:{signature}
cr:datacontainer:{scope}:{tableName}
cr:datastore:{namespace}:{logicalId}
cr:endpoint:{qualifiedRepo}:{specPath}:{METHOD}:{path}

These four URNs drive most of the blast-radius and cross-service topology correctness issues.

DataContainer Identity

DataContainer nodes represent logical database tables:

cr:datacontainer:{scope}:{tableName}

Scope resolution is intentionally simple pre-1.0:

1. databases[].tables in coderadius.yaml wins.
2. Otherwise, fall back to {qualifiedRepo}.

That means:

• private tables remain repo-scoped by default;
• shared tables converge only when explicitly declared;
• there is no automatic cross-repo convergence based on inferred DB connection labels.

Examples:

cr:datacontainer:acme/orders:orders
cr:datacontainer:shared-orders-db:orders

The DataContainer node also stores explicit metadata such as scope, scopeSource, and sourceRepo. Query-side code must use those properties rather than trying to reverse-parse the URN.

Datastore Identity

Datastore nodes represent physical or logical backing stores:

cr:datastore:{namespace}:{logicalId}

Examples:

cr:datastore:acme/orders:main-mysql
cr:datastore:acme/orders:redis-cache
cr:datastore:shared:kafka-cluster

Rules:

• {logicalId} comes from coderadius.yaml databases[].id.
• {namespace} is {qualifiedRepo} by default.
• Shared infrastructure uses shared.
• In fallback mode, the logical ID may be auto-{technology}.

In the graph model:

• DataContainer and Datastore are different layers.
• databases[].tables controls both the DataContainer URN scope and [:STORED_IN] linkage.
• The unified databases array replaces the former database_scope and datastores keys.

That separation allows a shared logical table scope and a repo-local physical datastore to coexist when that reflects reality.

API Identity

CodeRadius models three distinct API identities:

API Interface

cr:api:code-inferred:{qualifiedRepo}:{serviceName}
cr:api:{qualifiedRepo}:{serviceName}:{specPath}

The first form is produced from code analysis. The second form is produced from OpenAPI documents.

API Endpoint

cr:endpoint:code:{METHOD}:{path}
cr:endpoint:emergent:{METHOD}:{path}
cr:endpoint:{qualifiedRepo}:{specPath}:{METHOD}:{path}

The OpenAPI endpoint form is deliberately repo- and spec-scoped to avoid the old double-prefix and cross-repo collision problems.

Function Identity

Function nodes are globally unique only if they include the qualified repository:

cr:function:{qualifiedRepo}:{language}:{signature}

Examples:

cr:function:acme/orders:php:App\\Repository\\OrderRepository::findById
cr:function:acme/orders:typescript:src/lib/http/client::request

Using only the short repo basename is not sufficient in enterprise or monorepo-heavy environments.

Case Normalization

The URN builder lowercases all segments for these types:

• datacontainer
• datastore
• systemprocess
• domain
• system
• team
• tenant
• deploymentunit
• technology

Everything else is preserved verbatim.

This behavior is defined in src/graph/urn.ts.

Configuration Inputs

Two config surfaces are relevant to this taxonomy:

databases

Used to decide both the DataContainer namespace and which Datastore node receives [:STORED_IN] links:

databases:
  - id: shared-orders-db
    technology: mysql
    shared: true
    tables:
      - orders
      - shipments
  - id: redis-cache
    technology: redis

This produces:

cr:datacontainer:shared-orders-db:orders
cr:datacontainer:shared-orders-db:shipments
cr:datastore:shared:shared-orders-db
cr:datastore:acme/orders:redis-cache

Reference: coderadius.yaml Reference

Pre-1.0 Policy

This taxonomy is defined for a pre-1.0 / greenfield graph:

• no backward compatibility is guaranteed;
• breaking URN changes require a fresh ingest;
• correctness of identity is preferred over migration convenience.

In practice, when a breaking URN change lands, use:

cr analyze code --force

Related Docs

• coderadius.yaml Reference
• Ingestion Pipeline