Lesson 1: Canonical IDs

The Problem: ID Collisions

In a multi-repo system, multiple teams might use the same IDs:

• Repo A: API container
• Repo B: API container
• Repo C: API container

How do we distinguish them?

Solution: Canonical IDs

Every element gets a canonical ID with format:

repo_id::local_id

Examples:

• user-service::UserAPI
• order-service::OrderAPI
• payment-service::PaymentAPI

How Canonical IDs Work

In repo.sruja (local)

UserService = system "User Service" {
  UserAPI = container "User API" {
    description "REST API for user management"
  }
}

In system index (composed)

The compose process adds canonical IDs:

{
  "nodes": [
    {
      "canonical_id": "user-service::UserAPI",
      "repo_id": "user-service",
      "local_id": "UserAPI",
      "kind": "container",
      "label": "User API"
    }
  ]
}

Referencing Across Repos

In DSL imports

// In order-service/repo.sruja
import { user-service } from "../bundles/user-service.bundle.json"

OrderService = system "Order Service" {
  OrderProcessor = container "Order Processor"

  // Use canonical reference
  OrderProcessor -> user-service::UserAPI "Validates customer"
}

In queries

# Query specific repo's component
sruja query --canonical "user-service::UserAPI"

# Query all components of a repo
sruja query --repo user-service

ID Generation Rules

Best Practices

Next Steps

Lesson 2 covers external references between repos.