@eventcatalog/core 5.0.0-beta.11 → 5.0.0-beta.13

package/eventcatalog/src/features/studio/agent-choreography.ts

@@ -9,11 +9,16 @@ import {
   fitContainersAround,
   getCanvasMaps,
   moveNode,
-  resizeNode,
+  placeNode,
+  setEdgeRoutes,
   setMeta,
   type Author,
   type CommentAnchor,
-} from './canvas-doc';
+  getAbsolutePosition,
+  sizeOf,
+  type LayoutResult,
+  getNodeName,
+} from '@eventcatalog/visualiser/studio';
 import {
   describeNode,
   nodeCenter,
@@ -27,9 +32,6 @@ import {
   type NodeUpdate,
 } from './canvas-actions';
 import { getRelatedEdges } from './catalog';
-import { getAbsolutePosition, sizeOf } from './grouping';
-import type { LayoutResult } from './layout';
-import { getNodeName } from './node-types';
 
 /**
  * Agents work on a canvas like a person would: their cursor travels to where they're going, they drop one node,
@@ -292,13 +294,14 @@ export async function playLayout(stage: AgentStage, layout: LayoutResult) {
   hand.say('Done');
 }
 
-/** Moves nodes and resizes containers from a layout, in one change, and marks when it happened */
+/**
+ * Moves nodes, resizes containers and routes connections from a layout, in one change, and marks when it
+ * happened. Connections the layout didn't route lose their old route (drawn as a plain step instead).
+ */
 export const applyLayout = (doc: Y.Doc, layout: LayoutResult) =>
   doc.transact(() => {
-    layout.forEach(({ position, size }, id) => {
-      moveNode(doc, id, position);
-      if (size) resizeNode(doc, id, size);
-    });
+    layout.nodes.forEach(({ position, size }, id) => placeNode(doc, id, position, size));
+    setEdgeRoutes(doc, layout.routes);
     setMeta(doc, { layoutAt: Date.now() });
   });
 

package/eventcatalog/src/features/studio/agents.ts

@@ -0,0 +1,28 @@
+/**
+ * Who an agent is, named after its client when it doesn't say, in its brand's colour: on the server (MCP tools) and
+ * in a chat's canvas view (which joins as the chat's agent). Their logos are in the visualiser's ClientLogos.
+ */
+export type AgentIdentity = { name: string; color: string };
+
+const AGENT_COLORS: Record<string, string> = {
+  ChatGPT: '#10a37f',
+  Codex: '#10a37f',
+  Claude: '#d97757',
+  'Claude Code': '#d97757',
+  Cursor: '#111827',
+};
+
+/** Agents' clients, by what's in their user agent or host name (most specific first) */
+const CLIENTS: [RegExp, string][] = [
+  [/claude[-_ ]?code/i, 'Claude Code'],
+  [/claude|anthropic/i, 'Claude'],
+  [/codex/i, 'Codex'],
+  [/openai|chatgpt/i, 'ChatGPT'],
+  [/cursor/i, 'Cursor'],
+];
+
+/** Who the agent is, from the name it gives, else its client's user agent (or a chat's host name) */
+export const getAgent = (agentName: string | undefined, client = ''): AgentIdentity => {
+  const name = agentName?.trim() || CLIENTS.find(([pattern]) => pattern.test(client))?.[1] || 'AI agent';
+  return { name, color: AGENT_COLORS[name] ?? '#8b5cf6' };
+};

package/eventcatalog/src/features/studio/api/canvases-api.ts

@@ -1,7 +1,10 @@
 import { Hono, type Context } from 'hono';
 import { z } from 'zod';
 import { paginate } from '@features/tools/catalog-tools';
-import { MAX_TITLE_LENGTH, type CanvasStatus } from '../canvas-doc';
+import { type CanvasContent, type CanvasStatus } from '@eventcatalog/visualiser/studio';
+import { MAX_TITLE_LENGTH } from '../limits';
+import { diagramLevelsSchema, indexCatalog, newCanvasEdgesSchema, nodeSpecsSchema, planCanvas } from '../canvas-actions';
+import { getCatalogResources } from '../catalog-resources';
 import { MAX_NAME_LENGTH } from '../identity';
 import type { CanvasSummary, StudioRuntime } from '../server/runtime';
 import type { SignedInUser } from '../server/sign-in';
@@ -13,7 +16,13 @@ import type { SignedInUser } from '../server/sign-in';
  *
  *   GET    /api/studio/canvases        Canvases, most recently changed first (?pageSize=, ?cursor= for the next page)
  *                                       (not ones left empty and untitled: GET /:id still finds them)
- *   POST   /api/studio/canvases        Creates one: { "title"?: string, "createdBy"?: string }
+ *   POST   /api/studio/canvases        Creates one: { "title"?: string, "createdBy"?: string, "nodes"?: [...],
+ *                                       "edges"?: [...] }, starting with the nodes and edges given, if any (as the
+ *                                       add_to_canvas MCP tool takes them: catalog resources or new components, x/y
+ *                                       their centres, and only the connections in edges are made, each drawn
+ *                                       along its "route" if given: { "points": [{x, y}, ...], "label"?: {x, y} }),
+ *                                       and "levels" (L1 and L2 laid out, e.g. as a diagram shows them, by the
+ *                                       nodes' refs), shown as given until what's on the canvas changes
  *   GET    /api/studio/canvases/:id    One canvas
  *   POST   /api/studio/canvases/:id/copy   Copies its design (nodes and connections, not comments or status) to a new
  *                                         draft: { "title"?: string, "createdBy"?: string }
@@ -57,11 +66,23 @@ export type CanvasesApiEnv = {
   };
 };
 
+const MAX_NODES = 1000;
+const MAX_EDGES = 2000;
+
 const NewCanvas = z.object({
   title: z.string().trim().max(MAX_TITLE_LENGTH).optional(),
   // Ignored when someone's signed in: it's them
   createdBy: z.string().trim().max(MAX_NAME_LENGTH).optional(),
 });
+// A new canvas can start with nodes and edges; a copy starts with the original's
+const NewCanvasWithContent = NewCanvas.extend({
+  nodes: nodeSpecsSchema.max(MAX_NODES).optional(),
+  edges: newCanvasEdgesSchema.max(MAX_EDGES).optional(),
+  levels: diagramLevelsSchema.optional(),
+}).refine((canvas) => !canvas.edges?.length || canvas.nodes, {
+  message: 'Edges connect the nodes given with them: give nodes too',
+  path: ['edges'],
+});
 const ListQuery = z.object({
   cursor: z.string().optional(),
   pageSize: z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).optional(),
@@ -86,26 +107,54 @@ const describeIssues = (error: z.ZodError) =>
 type ApiContext = Context<CanvasesApiEnv>;
 const noCanvas = (c: ApiContext, id: string) => c.json({ error: `No canvas "${id}"` }, 404);
 
-/** A new canvas's details from the request (optional), or the response saying what's wrong with them */
-const readNewCanvas = async (c: ApiContext): Promise<{ title?: string; createdBy?: string } | Response> => {
+type NewCanvasDetails = { title?: string; createdBy?: string };
+
+/** The request's JSON body (or {} without one), or the response saying what's wrong with it */
+const readJson = async (c: ApiContext): Promise<unknown> => {
   // JSON only: a page on another site can send a form or plain text here without asking first, but not JSON
   const body = await c.req.text();
   if (body && !c.req.header('content-type')?.toLowerCase().startsWith('application/json')) {
     return c.json({ error: 'Send the canvas as JSON (Content-Type: application/json)' }, 415);
   }
-  let json: unknown = {};
   try {
-    if (body) json = JSON.parse(body);
+    return body ? JSON.parse(body) : {};
   } catch {
     return c.json({ error: 'The body is not valid JSON' }, 400);
   }
+};
+
+const detailsOf = (c: ApiContext, canvas: z.output<typeof NewCanvas>): NewCanvasDetails => ({
+  title: canvas.title || undefined,
+  // Whoever's signed in, if anyone
+  createdBy: c.env.signedInAs?.name ?? (canvas.createdBy || undefined),
+});
+
+/** A copy's details from the request (optional), or the response saying what's wrong with them */
+const readCopy = async (c: ApiContext): Promise<NewCanvasDetails | Response> => {
+  const json = await readJson(c);
+  if (json instanceof Response) return json;
   const parsed = NewCanvas.safeParse(json);
   if (!parsed.success) return c.json({ error: describeIssues(parsed.error) }, 400);
-  return {
-    title: parsed.data.title || undefined,
-    // Whoever's signed in, if anyone
-    createdBy: c.env.signedInAs?.name ?? (parsed.data.createdBy || undefined),
-  };
+  return detailsOf(c, parsed.data);
+};
+
+/** A new canvas's details and what it starts with (all optional), or the response saying what's wrong with them */
+const readNewCanvas = async (c: ApiContext): Promise<{ details: NewCanvasDetails; content?: CanvasContent } | Response> => {
+  const json = await readJson(c);
+  if (json instanceof Response) return json;
+  const parsed = NewCanvasWithContent.safeParse(json);
+  if (!parsed.success) return c.json({ error: describeIssues(parsed.error) }, 400);
+  const details = detailsOf(c, parsed.data);
+  if (!parsed.data.nodes) return { details };
+  const { resources, relations } = await getCatalogResources();
+  const { content, errors } = planCanvas(
+    parsed.data.nodes,
+    parsed.data.edges ?? [],
+    indexCatalog(resources, relations),
+    parsed.data.levels
+  );
+  if (errors.length) return c.json({ error: errors.join('; ') }, 400);
+  return { details, content };
 };
 
 /** The API, served under `basePath` (the catalog's base URL, then CANVASES_API_PATH) */
@@ -132,15 +181,15 @@ export const createCanvasesApi = (basePath: string) => {
   };
 
   app.post('/', async (c) => {
-    const details = await readNewCanvas(c);
-    if (details instanceof Response) return details;
-    return created(c, await c.env.runtime.createCanvas(details));
+    const canvas = await readNewCanvas(c);
+    if (canvas instanceof Response) return canvas;
+    return created(c, await c.env.runtime.createCanvas(canvas.details, canvas.content));
   });
 
   app.post('/:id/copy', async (c) => {
     const id = c.req.param('id');
     if (!CANVAS_ID.test(id)) return noCanvas(c, id);
-    const details = await readNewCanvas(c);
+    const details = await readCopy(c);
     if (details instanceof Response) return details;
     const copyId = await c.env.runtime.copyCanvas(id, details);
     return copyId ? created(c, copyId) : noCanvas(c, id);

package/eventcatalog/src/features/studio/api/client.ts

@@ -1,4 +1,5 @@
 import type { ApiCanvas } from './canvases-api';
+import type { DiagramLevelsSpec, NewCanvasEdges, NodeSpecs } from '../canvas-actions';
 
 /** Using the Studio API from the browser (Studio's pages), at `apiUrl` (its address on this catalog) */
 
@@ -7,7 +8,11 @@ const errorOf = async (response: Response, fallback: string) => {
   return new Error(body?.error ?? `${fallback} (${response.status})`);
 };
 
-export const createCanvasThroughApi = async (apiUrl: string, canvas: { title?: string; createdBy?: string }) => {
+/** Creates a canvas, starting with the nodes and edges given, if any */
+export const createCanvasThroughApi = async (
+  apiUrl: string,
+  canvas: { title?: string; createdBy?: string; nodes?: NodeSpecs; edges?: NewCanvasEdges; levels?: DiagramLevelsSpec }
+) => {
   const response = await fetch(apiUrl, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', Accept: 'application/json' },

package/eventcatalog/src/features/studio/canvas-actions.ts

@@ -1,21 +1,20 @@
 import type { Edge, Node, XYPosition } from '@xyflow/react';
 import type * as Y from 'yjs';
 import { z } from 'zod';
-import { buildNode, getCanvasMaps, getCanvasStatus, readCanvas, updateNodeData } from './canvas-doc';
-import type { CatalogRelation, CatalogResource } from './catalog-resources';
-import {
-  buildContainer,
-  canBeContainer,
-  catalogNodeData,
-  containerTypeFor,
-  getCatalogLink,
-  getRelatedEdges,
-  indexRelations,
-} from './catalog';
-import { findGroupAtPoint, getAbsolutePosition, sizeOf } from './grouping';
-import { placeNodes, type Link } from './placement';
 import {
+  buildNode,
+  getCanvasMaps,
+  getCanvasStatus,
+  readCanvas,
+  updateNodeData,
+  type CanvasContent,
+  containerFor,
+  getAbsolutePosition,
+  sizeOf,
+  placeNodes,
+  type Link,
   canGoInContainer,
+  CATALOG_COLLECTIONS,
   COMPONENT_TYPES,
   getNodeDefinition,
   getNodeLabel,
@@ -27,24 +26,23 @@ import {
   isVersioned,
   isWrittenOnCanvas,
   updateResource,
-} from './node-types';
+} from '@eventcatalog/visualiser/studio';
+import type { CatalogRelation, CatalogResource } from './catalog-resources';
+import {
+  buildContainer,
+  canBeContainer,
+  catalogNodeData,
+  containerTypeFor,
+  getCatalogLink,
+  getRelatedEdges,
+  indexRelations,
+} from './catalog';
 
 /**
  * What agents can do on a canvas, shared by the MCP tools (on the server) and the WebMCP tools (in the
  * browser), so both describe and change a canvas the same way.
  */
 
-export const CATALOG_COLLECTIONS = [
-  'domains',
-  'systems',
-  'services',
-  'events',
-  'commands',
-  'queries',
-  'channels',
-  'containers',
-] as const;
-
 // ---- Inputs ----
 
 export const nodeSpecsSchema = z
@@ -71,6 +69,16 @@ export const nodeSpecsSchema = z
         .describe('A ref (or node id) of a container (a domain or system added as one) to put this node inside'),
       x: z.number().optional(),
       y: z.number().optional(),
+      width: z
+        .number()
+        .positive()
+        .optional()
+        .describe('For a container: its width to start with (it grows to fit what is put in it)'),
+      height: z
+        .number()
+        .positive()
+        .optional()
+        .describe('For a container: its height to start with (it grows to fit what is put in it)'),
     })
   )
   .min(1);
@@ -83,6 +91,83 @@ export const edgeSpecsSchema = z.array(
   })
 );
 
+const pointSchema = z.object({ x: z.number(), y: z.number() });
+
+/**
+ * Edges for a new canvas (through the Studio API): as add_to_canvas takes them, and how each is drawn, if known
+ * (e.g. copied from a diagram): the points it goes through (canvas coordinates, at right angles) and where its
+ * label goes. It follows its nodes when they're moved.
+ */
+const routeSchema = z.object({ points: z.array(pointSchema).min(2).max(200), label: pointSchema.optional() });
+export const newCanvasEdgesSchema = z.array(edgeSpecsSchema.element.extend({ route: routeSchema.optional() }));
+export type NewCanvasEdges = z.output<typeof newCanvasEdgesSchema>;
+
+const MAX_LEVEL_NODES = 1000;
+const levelSchema = z.object({
+  nodes: z
+    .array(
+      z.object({
+        ref: z.string().describe("The ref of the node it is on the canvas (or its own id, if it's only on this level)"),
+        type: z.string(),
+        data: z.record(z.string(), z.unknown()),
+        parent: z.string().optional().describe('The ref of the node it is shown in on this level'),
+        x: z.number().describe('Its top-left corner (relative to its parent)'),
+        y: z.number(),
+        width: z.number().positive().optional().describe('For a container: its size'),
+        height: z.number().positive().optional(),
+      })
+    )
+    .max(MAX_LEVEL_NODES),
+  edges: z
+    .array(
+      z.object({
+        from: z.string(),
+        to: z.string(),
+        label: z.string().optional(),
+        type: z.string().optional(),
+        style: z.record(z.string(), z.unknown()).optional(),
+        markerEnd: z.unknown().optional(),
+        data: z.record(z.string(), z.unknown()).optional().describe("The edge's data, e.g. its route"),
+      })
+    )
+    .max(MAX_LEVEL_NODES * 2),
+});
+
+/**
+ * L1 and L2 of the diagram a canvas is opened from, laid out as the diagram showed them (by refs of the nodes given
+ * for the canvas): shown as they are until the canvas's structure changes
+ */
+const unavailableReason = z.string().max(300).optional();
+export const diagramLevelsSchema = z.object({
+  1: levelSchema.optional(),
+  2: levelSchema.optional(),
+  unavailable: z
+    .object({ 1: unavailableReason, 2: unavailableReason })
+    .optional()
+    .describe("Levels the diagram doesn't have, and why"),
+});
+export type DiagramLevelsSpec = z.output<typeof diagramLevelsSchema>;
+
+/** A diagram's level, with refs swapped for the ids of the nodes made for them */
+const toDiagramLevel = (level: z.output<typeof levelSchema>, idOf: (ref: string) => string) => {
+  const shown = new Set(level.nodes.map((node) => node.ref));
+  return {
+    nodes: level.nodes.map(
+      ({ ref, type, data, parent, x, y, width, height }): Node => ({
+        id: idOf(ref),
+        type,
+        data,
+        position: { x, y },
+        ...(parent && shown.has(parent) && { parentId: idOf(parent) }),
+        ...(width && height && { style: { width, height } }),
+      })
+    ),
+    edges: level.edges
+      .filter((edge) => shown.has(edge.from) && shown.has(edge.to))
+      .map(({ from, to, ...edge }, index) => ({ ...edge, id: `diagram-${index}`, source: idOf(from), target: idOf(to) }) as Edge),
+  };
+};
+
 export const ADD_TO_CANVAS_DESCRIPTION = [
   'Adds nodes (and connections between them) to the canvas, live for everyone on it.',
   'A node is either a catalog resource (resource: { collection, id }), shown with its real name and summary and automatically connected to the related resources already on the canvas (e.g. a service to the events it publishes), or a new component (type, name, summary) for things that are not in the catalog yet, like a proposed service.',
@@ -199,6 +284,13 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
   const errors: string[] = [];
   const hasPosition = (spec: { x?: number; y?: number }) => spec.x !== undefined && spec.y !== undefined;
   const centerOf = (spec: { x?: number; y?: number }) => (hasPosition(spec) ? { x: spec.x!, y: spec.y! } : { x: 0, y: 0 });
+  // A container at the size asked for, still centred where asked
+  const sized = (node: Node, spec: { x?: number; y?: number; width?: number; height?: number }): Node => {
+    if (!isGroupType(node.type) || !spec.width || !spec.height) return node;
+    const center = centerOf(spec);
+    const { width, height } = spec;
+    return { ...node, width, height, position: { x: center.x - width / 2, y: center.y - height / 2 } };
+  };
 
   // Inside a container, at the canvas point asked for (relative to the container)
   const putInside = (node: Node, parent: Node, spec: { x?: number; y?: number }): Node => {
@@ -222,7 +314,7 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
       }
       const asContainer = spec.container && canBeContainer(resource);
       const node = asContainer
-        ? buildContainer(resource, centerOf(spec))
+        ? sized(buildContainer(resource, centerOf(spec)), spec)
         : buildNode(resource.node.type, catalogNodeData(resource), centerOf(spec));
       built = { node, name: resource.name, resource };
     } else {
@@ -238,7 +330,7 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
             ...(spec.summary && { summary: spec.summary }),
             ...(spec.version && isVersioned(definition.type) && { version: spec.version }),
           });
-      const node = buildNode(definition.type, data, centerOf(spec));
+      const node = sized(buildNode(definition.type, data, centerOf(spec)), spec);
       built = { node, name: String(getResource(node.type, node.data).name ?? definition.label) };
     }
 
@@ -297,11 +389,44 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
 };
 
 /** Edges given by refs (or ids of nodes already on the canvas), as node ids */
-export const resolveEdgeRefs = (edges: EdgeSpecs, planned: PlannedNode[]) => {
-  const refs = new Map(planned.flatMap((entry) => (entry.ref ? [[entry.ref, entry.node.id] as const] : [])));
+const refIds = (planned: PlannedNode[]) =>
+  new Map(planned.flatMap((entry) => (entry.ref ? [[entry.ref, entry.node.id] as const] : [])));
+
+export const resolveEdgeRefs = <Spec extends EdgeSpecs[number]>(edges: Spec[], planned: PlannedNode[]) => {
+  const refs = refIds(planned);
   return edges.map((edge) => ({ ...edge, from: refs.get(edge.from) ?? edge.from, to: refs.get(edge.to) ?? edge.to }));
 };
 
+/**
+ * A new canvas's content from nodes and edges given as add_to_canvas takes them. Only the connections asked for
+ * are made: related catalog resources aren't connected as well, so the canvas shows just what was asked for (e.g.
+ * a diagram's connections, which may go through channels). Says what's wrong if anything can't be followed.
+ */
+export const planCanvas = (
+  specs: NodeSpecs,
+  edges: NewCanvasEdges,
+  catalog: CatalogIndex,
+  levels?: DiagramLevelsSpec
+): { content: CanvasContent; errors: string[] } => {
+  const { planned, errors } = planNodes([], specs, catalog, edges);
+  const ids = new Set(planned.map((entry) => entry.node.id));
+  const connections = resolveEdgeRefs(edges, planned);
+  for (const end of connections.flatMap((connection) => [connection.from, connection.to])) {
+    if (!ids.has(end)) errors.push(`Edges connect nodes by their ref: no node has the ref "${end}"`);
+  }
+  const refs = refIds(planned);
+  const idOf = (ref: string) => refs.get(ref) ?? ref;
+  const diagramLevels = levels && {
+    ...(levels[1] && { 1: toDiagramLevel(levels[1], idOf) }),
+    ...(levels[2] && { 2: toDiagramLevel(levels[2], idOf) }),
+    ...(levels.unavailable && { unavailable: levels.unavailable }),
+  };
+  return {
+    content: { nodes: planned.map((entry) => entry.node), connections, ...(diagramLevels && { levels: diagramLevels }) },
+    errors: [...new Set(errors)],
+  };
+};
+
 export type NodeUpdate = { nodeId: string; name?: string; summary?: string; version?: string };
 
 /** Renames, re-describes or re-versions a node. Catalog resources keep their catalog name, summary and version. */
@@ -377,9 +502,9 @@ export const getCatalogConnections = (
 };
 
 /**
- * A catalog resource centred on a canvas point (inside the container there, if there is one), with the resources
- * it connects to placed around it like an architect would (what comes in before it, what goes out after it), and
- * the connections between them and to what's already on the canvas. A service's data stores go in its container
+ * A catalog resource centred on a canvas point (inside the container asked for, else the one there, if any), with
+ * the resources it connects to placed around it like an architect would (what comes in before it, what goes out
+ * after it), and the connections between them and to what's already on the canvas. A service's data stores go in its container
  * with it. Positions are relative to the containers they're in, as the canvas is now.
  */
 export const planWithConnections = (
@@ -387,9 +512,10 @@ export const planWithConnections = (
   resource: CatalogResource,
   center: XYPosition,
   include: CatalogResource[],
-  catalog: CatalogIndex
+  catalog: CatalogIndex,
+  inside?: string
 ): { nodes: Node[]; edges: Edge[] } => {
-  const container = findGroupAtPoint(center, existing);
+  const container = containerFor(center, existing, inside);
   const specOf = (entry: CatalogResource) => ({
     resource: { collection: entry.collection as (typeof CATALOG_COLLECTIONS)[number], id: entry.id },
   });

package/eventcatalog/src/features/studio/canvas-preview.ts

@@ -1,6 +1,5 @@
 import type { Edge, Node } from '@xyflow/react';
-import { getAbsolutePosition, sizeOf } from './grouping';
-import { isGroupType } from './node-types';
+import { getAbsolutePosition, sizeOf, isGroupType } from '@eventcatalog/visualiser/studio';
 
 /**
  * A canvas drawn small, for lists of canvases: each node as a box where it is on the canvas (containers as outlines

package/eventcatalog/src/features/studio/catalog.ts

@@ -1,9 +1,6 @@
 import type { Edge, Node } from '@xyflow/react';
 import type { CatalogRelation, CatalogResource } from './catalog-resources';
-import { buildNode } from './canvas-doc';
-import { createEdge } from './edges';
-import { layoutGraph, withGroupSizes } from './layout';
-import { GROUP_TYPES, isGroupType } from './node-types';
+import { buildNode, createEdge, layoutGraph, withGroupSizes, GROUP_TYPES, isGroupType } from '@eventcatalog/visualiser/studio';
 
 /**
  * Catalog resources on a canvas: the node for a resource, its connections to related resources already there,
@@ -66,16 +63,21 @@ export const canBeContainer = (resource: CatalogResource) =>
 export const containerTypeFor = (resource: CatalogResource) =>
   resource.collection === 'domains' ? GROUP_TYPES.domain : GROUP_TYPES.system;
 
-/** A container's data: the domain or system it stands for, and where it is in the catalog */
-export const catalogGroupData = (resource: CatalogResource) => ({
-  [resource.collection === 'domains' ? 'domain' : 'system']: {
-    id: resource.id,
-    name: resource.name,
-    version: resource.version,
-    summary: resource.summary,
-  },
-  catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
-});
+/** A container's data: the domain or system it stands for (an external system marked as one), and where it is in the catalog */
+export const catalogGroupData = (resource: CatalogResource) => {
+  const key = resource.collection === 'domains' ? 'domain' : 'system';
+  const { scope } = (resource.node.data[key] ?? {}) as { scope?: string };
+  return {
+    [key]: {
+      id: resource.id,
+      name: resource.name,
+      version: resource.version,
+      summary: resource.summary,
+      ...(scope && { scope }),
+    },
+    catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
+  };
+};
 
 /** What a domain or system contains in the catalog: a domain's systems and services, a system's services */
 export const getContents = (