@eventcatalog/core 5.0.0-beta.2 → 5.0.0-beta.20

package/eventcatalog/src/utils/collections/resources.ts

@@ -0,0 +1,310 @@
+import { collectionToResourceMap, resourceKey, uniqueResources } from '@utils/collections/util';
+
+// What the Resources pages show: which resources each owner (domain, system, service, flow,
+// channel or message) lists, how each relates to the owner, and the links for each row.
+// Loading owners and their related resources lives in ./resource-owners.
+
+/** The kinds of resource a Resources page can list. */
+export type ResourceCollection =
+  | 'domains'
+  | 'systems'
+  | 'agents'
+  | 'services'
+  | 'flows'
+  | 'entities'
+  | 'data-products'
+  | 'containers'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'channels'
+  | 'adrs';
+
+/** How a resource relates to the page's owner: which way a message flows, how a data store is used, or how it belongs to the owner. */
+export type ResourceRelationship =
+  | 'receives'
+  | 'sends'
+  | 'sends-and-receives'
+  | 'reads'
+  | 'writes'
+  | 'reads-and-writes'
+  | 'contains'
+  | 'owns'
+  | 'appears-in'
+  | 'governed-by'
+  | 'includes'
+  | 'transports'
+  | 'produces-messages'
+  | 'receives-messages'
+  | 'produces-and-receives-messages'
+  | 'produces'
+  | 'consumes'
+  | 'produces-and-consumes'
+  | 'triggers'
+  | 'triggered-by'
+  | 'triggers-and-triggered-by';
+
+/** Any catalog entry a Resources page reads: a collection entry, possibly hydrated with extra fields. */
+export type ResourceEntry = {
+  collection: string;
+  data: { id: string; version: string; name?: string; summary?: string; [key: string]: any };
+  [key: string]: any;
+};
+
+export type ResourceOwnerCollection = 'systems' | 'domains' | 'services' | 'flows' | 'channels' | MessageOwnerCollection;
+type MessageOwnerCollection = 'events' | 'commands' | 'queries';
+const isMessageOwner = (collection: ResourceOwnerCollection): collection is MessageOwnerCollection =>
+  collection === 'events' || collection === 'commands' || collection === 'queries';
+
+/** Resources that point at the owner, rather than being listed in the owner's own frontmatter. */
+export interface RelatedResources {
+  /** Decision records whose `appliesTo` includes the owner. */
+  adrs?: ResourceEntry[];
+  /** Flows with a step that points at the owner (services only). */
+  stepFlows?: ResourceEntry[];
+  /** The resources a flow's steps point at (flows only). */
+  stepResources?: ResourceEntry[];
+  /** Services and agents that send to the channel, those that receive from it, and the messages on it (channels only). */
+  channelProducers?: ResourceEntry[];
+  channelConsumers?: ResourceEntry[];
+  channelMessages?: ResourceEntry[];
+  /** The channels, flows and messages a message connects to (messages only; its producers and consumers are on `data`). */
+  messageChannels?: ResourceEntry[];
+  messageFlows?: ResourceEntry[];
+  messageTriggers?: ResourceEntry[];
+  messageTriggeredBy?: ResourceEntry[];
+}
+
+/** A resource owner as the Resources page receives it: the collection entry with its related resources attached. */
+export type ResourceOwner = ResourceEntry & RelatedResources;
+
+export interface ResourceGroup {
+  collection: ResourceCollection;
+  items: ResourceEntry[];
+}
+
+const getMessages = (data: any) =>
+  uniqueResources([...(data.sends || []), ...(data.receives || [])].filter((message) => message?.collection));
+
+const messageGroups = (messages: any[]): ResourceGroup[] => [
+  { collection: 'events', items: messages.filter((message) => message.collection === 'events') },
+  { collection: 'commands', items: messages.filter((message) => message.collection === 'commands') },
+  { collection: 'queries', items: messages.filter((message) => message.collection === 'queries') },
+];
+
+// The collections a flow step can point at, in the order the page groups them.
+const FLOW_STEP_COLLECTIONS: ResourceCollection[] = [
+  'services',
+  'agents',
+  'flows',
+  'containers',
+  'data-products',
+  'events',
+  'commands',
+  'queries',
+];
+
+export const getResourceGroups = (
+  data: any,
+  ownerCollection: ResourceOwnerCollection,
+  related: RelatedResources = {}
+): ResourceGroup[] => {
+  const adrGroup: ResourceGroup = { collection: 'adrs', items: related.adrs || [] };
+
+  // A message's resources are what produces or consumes it, the channels it travels on, the
+  // flows it appears in, and the messages it triggers or is triggered by.
+  if (isMessageOwner(ownerCollection)) {
+    const endpoints = uniqueResources([...(data.producers || []), ...(data.consumers || [])]);
+    const endpointGroup = (collection: ResourceCollection): ResourceGroup => ({
+      collection,
+      items: endpoints.filter((endpoint) => endpoint.collection === collection),
+    });
+    return [
+      endpointGroup('services'),
+      endpointGroup('agents'),
+      endpointGroup('data-products'),
+      { collection: 'channels', items: related.messageChannels || [] },
+      { collection: 'flows', items: related.messageFlows || [] },
+      ...messageGroups(uniqueResources([...(related.messageTriggers || []), ...(related.messageTriggeredBy || [])])),
+      adrGroup,
+    ];
+  }
+
+  // A channel's resources are the services and agents that send to or receive from it, and the messages on it.
+  if (ownerCollection === 'channels') {
+    const endpoints = uniqueResources([...(related.channelProducers || []), ...(related.channelConsumers || [])]);
+    return [
+      { collection: 'services', items: endpoints.filter((endpoint) => endpoint.collection === 'services') },
+      { collection: 'agents', items: endpoints.filter((endpoint) => endpoint.collection === 'agents') },
+      ...messageGroups(related.channelMessages || []),
+      adrGroup,
+    ];
+  }
+
+  // A flow's resources are what its steps point at.
+  if (ownerCollection === 'flows') {
+    const stepResources = related.stepResources || [];
+    return [
+      ...FLOW_STEP_COLLECTIONS.map((collection) => ({
+        collection,
+        items: stepResources.filter((resource) => resource.collection === collection),
+      })),
+      adrGroup,
+    ];
+  }
+
+  // A service's resources are what it uses: the messages it sends and receives, its
+  // entities, the data stores it reads from or writes to, and the flows it appears in.
+  if (ownerCollection === 'services') {
+    return [
+      { collection: 'flows', items: uniqueResources([...(data.flows || []), ...(related.stepFlows || [])]) },
+      { collection: 'entities', items: data.entities || [] },
+      { collection: 'containers', items: uniqueResources([...(data.writesTo || []), ...(data.readsFrom || [])]) },
+      ...messageGroups(getMessages(data)),
+      adrGroup,
+    ];
+  }
+
+  const domainOnlyGroups: ResourceGroup[] =
+    ownerCollection === 'domains'
+      ? [
+          { collection: 'domains', items: data.domains || [] },
+          { collection: 'systems', items: data.systems || [] },
+          { collection: 'agents', items: data.agents || [] },
+          { collection: 'data-products', items: data['data-products'] || [] },
+        ]
+      : [];
+
+  return [
+    ...domainOnlyGroups,
+    { collection: 'services', items: data.services || [] },
+    { collection: 'flows', items: data.flows || [] },
+    { collection: 'entities', items: data.entities || [] },
+    { collection: 'containers', items: data.containers || [] },
+    ...messageGroups(ownerCollection === 'domains' ? getMessages(data) : []),
+    adrGroup,
+  ];
+};
+
+// The page loader attaches the RelatedResources fields to the owner (see _index.data.ts).
+export const hasResources = (owner: any, ownerCollection: ResourceOwnerCollection): boolean =>
+  getResourceGroups(owner?.data ?? {}, ownerCollection, owner ?? {}).some(({ items }) => items.length > 0);
+
+const includesResource = (resources: any[] | undefined, item: any) =>
+  (resources || []).some((resource) => resource?.data && resourceKey(resource) === resourceKey(item));
+
+/**
+ * How a resource relates to the page's owner: which way a message flows, how a data store
+ * is used, or whether the owner contains, owns or appears in it.
+ */
+export const getResourceRelationship = (
+  data: any,
+  ownerCollection: ResourceOwnerCollection,
+  collection: ResourceCollection,
+  item: any,
+  related: RelatedResources = {}
+): ResourceRelationship | undefined => {
+  if (collection === 'adrs') return 'governed-by';
+  if (ownerCollection === 'flows') return 'includes';
+  if (isMessageOwner(ownerCollection)) {
+    if (collection === 'channels') return 'transports';
+    if (collection === 'flows') return 'appears-in';
+    if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+      const triggers = includesResource(related.messageTriggers, item);
+      const triggeredBy = includesResource(related.messageTriggeredBy, item);
+      if (triggers && triggeredBy) return 'triggers-and-triggered-by';
+      if (triggers) return 'triggers';
+      if (triggeredBy) return 'triggered-by';
+      return undefined;
+    }
+    const produces = includesResource(data.producers, item);
+    const consumes = includesResource(data.consumers, item);
+    if (produces && consumes) return 'produces-and-consumes';
+    if (produces) return 'produces';
+    if (consumes) return 'consumes';
+    return undefined;
+  }
+  // A channel transports messages; services and agents produce messages onto it or receive them from it.
+  if (ownerCollection === 'channels') {
+    if (collection !== 'services' && collection !== 'agents') return 'transports';
+    const produces = includesResource(related.channelProducers, item);
+    const receives = includesResource(related.channelConsumers, item);
+    if (produces && receives) return 'produces-and-receives-messages';
+    if (produces) return 'produces-messages';
+    if (receives) return 'receives-messages';
+    return undefined;
+  }
+  if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+    const sends = includesResource(data.sends, item);
+    const receives = includesResource(data.receives, item);
+    if (sends && receives) return 'sends-and-receives';
+    if (sends) return 'sends';
+    if (receives) return 'receives';
+    return undefined;
+  }
+  if (collection === 'entities') return 'owns';
+  if (ownerCollection === 'services') {
+    if (collection === 'flows') return 'appears-in';
+    if (collection === 'containers') {
+      const writes = includesResource(data.writesTo, item);
+      const reads = includesResource(data.readsFrom, item);
+      if (writes && reads) return 'reads-and-writes';
+      if (writes) return 'writes';
+      if (reads) return 'reads';
+    }
+    return undefined;
+  }
+  // Everything else on a domain or system page is part of it.
+  return 'contains';
+};
+
+/**
+ * The schema page for a resource, matching the sidebar's Schema link: messages with an entry
+ * in the schemas collection (keyed `collection:id:version`), and data products with an output
+ * contract. Undefined for everything else.
+ */
+export const getSchemaPath = (collection: ResourceCollection, item: any, schemaKeys: Set<string>) => {
+  const { id, version } = item.data;
+  if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+    return schemaKeys.has(`${collection}:${id}:${version}`) ? `/schemas/${collection}/${id}/${version}` : undefined;
+  }
+  if (collection === 'data-products') {
+    const contract = (item.data.outputs || []).find((output: any) => output.contract)?.contract;
+    return contract ? `/schemas/data-products/${id}/${version}?contract=${encodeURIComponent(contract.path)}` : undefined;
+  }
+  return undefined;
+};
+
+export const getDocsPath = (collection: ResourceCollection, item: any) =>
+  `/docs/${collection}/${item.data.id}/${item.data.version}`;
+
+// Collections the visualiser has a page for (domains and systems through their own routes).
+// Entities and decision records have none.
+const VISUALISER_COLLECTIONS = new Set<ResourceCollection>([
+  'domains',
+  'systems',
+  'agents',
+  'services',
+  'flows',
+  'containers',
+  'channels',
+  'data-products',
+  'events',
+  'commands',
+  'queries',
+]);
+
+/** The resource's visualiser page, unless the visualiser is off, has no page for it, or the resource opts out. */
+export const getVisualiserPath = (collection: ResourceCollection, item: any, visualiserEnabled: boolean) => {
+  if (!visualiserEnabled || !VISUALISER_COLLECTIONS.has(collection) || item.data.visualiser === false) return undefined;
+  return `/visualiser/${collection}/${item.data.id}/${item.data.version}`;
+};
+
+/** Same key and badge as the favorite button on the resource's docs page. */
+export const getFavorite = (collection: ResourceCollection, item: any) => {
+  const resourceType = collectionToResourceMap[collection];
+  return {
+    nodeKey: `${resourceType}:${item.data.id}:${item.data.version}`,
+    badge: resourceType.charAt(0).toUpperCase() + resourceType.slice(1),
+  };
+};

package/eventcatalog/src/utils/collections/util.ts

@@ -291,6 +291,37 @@ export const createVersionedMap = <T extends { data: { id: string; version?: str
   return map;
 };
 
+const versionedMapCache = new WeakMap<object, Map<string, any[]>>();
+
+/**
+ * createVersionedMap, built once per list. Use it in helpers that search the same list once per
+ * resource, so a catalog-wide pass does not rebuild the map every time.
+ */
+export const getVersionedMap = <T extends { data: { id: string; version?: string } }>(items: T[]): Map<string, T[]> => {
+  let map = versionedMapCache.get(items);
+  if (!map) {
+    map = createVersionedMap(items);
+    versionedMapCache.set(items, map);
+  }
+  return map as Map<string, T[]>;
+};
+
+type KeyedResource = { collection: string; data: { id: string; version?: string } };
+
+/** Identifies a resource across collections: a service and an agent can share an id and version. */
+export const resourceKey = (resource: KeyedResource) => `${resource.collection}:${resource.data.id}:${resource.data.version}`;
+
+/** The resources without repeats (by collection, id and version), keeping the first of each in order. */
+export const uniqueResources = <T extends KeyedResource>(resources: T[]): T[] => {
+  const seen = new Map<string, T>();
+  for (const resource of resources) {
+    if (!resource?.data?.id) continue;
+    const key = resourceKey(resource);
+    if (!seen.has(key)) seen.set(key, resource);
+  }
+  return [...seen.values()];
+};
+
 // Merge as many given maps as you want
 export const mergeMaps = <T>(...maps: Map<string, T[]>[]): Map<string, T[]> => {
   return maps.reduce((acc, map) => {

package/eventcatalog/src/utils/feature.ts

@@ -27,4 +27,12 @@ export const isAuthEnabled = () =>
   (config?.auth?.enabled ?? false) && fs.existsSync(join(projectDirectory(), 'eventcatalog.auth.js')) && isSSR();
 
 export const isEventCatalogMCPEnabled = () => isSSR() && (config?.mcp?.enabled ?? true);
+
+// Collaborative canvases (EventCatalog Studio, /studio) are an experiment: on the dev server (unless studio.enabled is
+// false), and in production (server output) when studio.enabled is set. With sign-in on, only signed-in people can
+// open them.
+export const isCanvasEnabled = () => {
+  const enabled = config?.studio?.enabled;
+  return enabled !== false && (isDevMode() || (isSSR() && enabled === true));
+};
 export const isEventCatalogMCPAuthEnabled = () => isEventCatalogMCPEnabled() && (config?.mcp?.auth?.enabled ?? false);

package/eventcatalog/src/utils/git.ts

@@ -1,7 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import shell from 'shelljs';
 
 type Commit = { timestamp: number; author: string };
 
@@ -9,10 +8,6 @@ const COMMIT_MARKER = '\x1e';
 
 const newestCommitsByRepository = new Map<string, Map<string, Commit> | undefined>();
 
-export function hasGit() {
-  return !!shell.which('git');
-}
-
 const runGit = (args: string[]) => {
   try {
     return execFileSync('git', ['-c', 'log.showSignature=false', ...args], {
@@ -25,6 +20,17 @@ const runGit = (args: string[]) => {
   }
 };
 
+// Checked once per PATH, as git history is read for every page
+const gitInstalledByPath = new Map<string | undefined, boolean>();
+
+export function hasGit() {
+  const searchPath = process.env.PATH;
+  if (!gitInstalledByPath.has(searchPath)) {
+    gitInstalledByPath.set(searchPath, runGit(['--version']) !== undefined);
+  }
+  return gitInstalledByPath.get(searchPath)!;
+}
+
 const parseCommit = (header: string): Commit => {
   const [timestamp, ...author] = header.split(',');
   return { timestamp: Number(timestamp) * 1_000, author: author.join(',') };

package/eventcatalog/src/utils/link-validation.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { parse, type DefaultTreeAdapterMap } from 'parse5';
+import { Parser } from 'htmlparser2';
 import picomatch from 'picomatch';
 
 export type LinkValidationSeverity = 'warn' | 'error' | 'ignore';
@@ -42,30 +42,36 @@ const decodeUrlPart = (value: string): string => {
   }
 };
 
+// Elements whose contents browsers don't render as markup (<noscript> when scripts run)
+const INERT_ELEMENTS = new Set(['template', 'noscript']);
+
 // Parse HTML rather than searching markup with a regex: attributes can contain
 // entities, quoted > characters, or single/unquoted values. Scripts and inert
 // template contents must not be mistaken for rendered links or anchor targets.
+// A streaming parser, not a document tree: pages can be large (island props),
+// and building a tree of each one made link validation a large part of a build.
 const readPage = (html: string, source: string): PageLinks => {
   const page: PageLinks = { source, anchors: new Set(), links: new Set() };
-  const nodes: DefaultTreeAdapterMap['node'][] = [parse(html)];
-  while (nodes.length > 0) {
-    const node = nodes.pop()!;
-    if ('tagName' in node) {
-      const attrs = new Map(node.attrs.map((attr) => [attr.name, attr.value]));
-      const id = attrs.get('id');
-      if (id) page.anchors.add(id);
-      if (node.tagName === 'a' && attrs.get('name')) page.anchors.add(attrs.get('name')!);
-      const href = attrs.get('href');
-      if (href !== undefined) {
-        if (node.tagName === 'base' && page.baseHref === undefined) page.baseHref = href;
-        if (node.tagName === 'a' || node.tagName === 'area') page.links.add(href);
+  let inert = 0;
+  const parser = new Parser({
+    onopentag(tagName, attrs) {
+      if (inert === 0) {
+        if (attrs.id) page.anchors.add(attrs.id);
+        if (tagName === 'a' && attrs.name) page.anchors.add(attrs.name);
+        const href = attrs.href;
+        if (href !== undefined) {
+          // Parsed in document order, so the first <base href> wins
+          if (tagName === 'base' && page.baseHref === undefined) page.baseHref = href;
+          if (tagName === 'a' || tagName === 'area') page.links.add(href);
+        }
       }
-    }
-    // Reverse the stack so the first <base href> wins in document order.
-    if ('childNodes' in node) {
-      for (let i = node.childNodes.length - 1; i >= 0; i--) nodes.push(node.childNodes[i]);
-    }
-  }
+      if (INERT_ELEMENTS.has(tagName)) inert++;
+    },
+    onclosetag(tagName) {
+      if (INERT_ELEMENTS.has(tagName) && inert > 0) inert--;
+    },
+  });
+  parser.end(html);
   return page;
 };
 

package/eventcatalog/src/utils/node-graphs/domain-entity-map.ts

@@ -212,7 +212,9 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
             height: 20,
           },
         });
-      } else {
+      } else if (!entityMap.has(referencedEntityId)) {
+        // Only a reference to an entity missing from the catalog is broken. An external entity's own
+        // references can point further away than this map shows: those edges are left out.
         console.warn(`Referenced entity "${referencedEntityId}" not found for ${entity.data.name}.${referenceProperty.name}`);
       }
     }

package/eventcatalog/src/utils/node-graphs/domain-levels-node-graph.ts

@@ -267,7 +267,7 @@ export const buildDomainGraph = ({
         draggable: false,
         selectable: false,
         data: {
-          domain: { name: d.data.name, version: d.data.version },
+          domain: { id: d.data.id, name: d.data.name, version: d.data.version },
           // The domain viewed may itself be a subdomain of another
           subdomain: !!parentId || parentDomainOf.has(d.data.id),
           isFocused: !parentId,
@@ -309,7 +309,7 @@ export const buildDomainGraph = ({
         position: { x: 0, y: 0 },
         ...(parentId ? { parentId } : {}),
         data: {
-          domain: { name: other.data.name, version: other.data.version },
+          domain: { id: other.data.id, name: other.data.name, version: other.data.version },
           subdomain: !!parentId,
           isFocused: false,
           otherDomain: true,
@@ -375,7 +375,7 @@ export const buildDomainGraph = ({
         type: 'system-group',
         parentId: domainGroup,
         position: { x: 0, y: 0 },
-        data: { system: { name: system.data.name, version: system.data.version } },
+        data: { system: { id: system.data.id, name: system.data.name, version: system.data.version } },
       });
     }
     addNodes(graph.nodes);

package/eventcatalog/src/utils/node-graphs/export-mermaid.ts

@@ -38,7 +38,6 @@ const NODE_SHAPE_MAP: Record<string, [string, string]> = {
   'context-actor': ['((', '))'], // circle
   flows: ['([', '])'], // stadium (rounded)
   flow: ['([', '])'],
-  systems: ['[[', ']]'],
   system: ['[[', ']]'],
   step: ['[', ']'], // rectangle
   user: ['((', '))'], // circle
@@ -79,7 +78,6 @@ const NODE_STYLE_CLASSES: Record<string, string> = {
   domains: 'fill:#eab308,stroke:#a16207,color:#000',
   domain: 'fill:#eab308,stroke:#a16207,color:#000',
   'context-domain': 'fill:#eab308,stroke:#a16207,color:#000',
-  systems: 'fill:#7c3aed,stroke:#5b21b6,color:#fff',
   'context-actor': 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
   flows: 'fill:#14b8a6,stroke:#0f766e,color:#fff',
   flow: 'fill:#14b8a6,stroke:#0f766e,color:#fff',

package/eventcatalog/src/utils/node-graphs/layout-node-graph.ts

@@ -1,7 +1,14 @@
 import { hideMessageNodes, layoutWithElk } from '@eventcatalog/visualiser/layout';
+import { isSSR } from '@utils/feature';
 
 type Graph = { nodes: any[]; edges: any[] };
 
+// A build renders one route at a time (every message's docs page, then every schema page), so the
+// cache has to outlast a whole route to be reused. A server keeps running as the catalog changes and
+// renders pages as they're asked for, so it keeps the most recent layouts only.
+const MAX_CACHED_LAYOUTS = isSSR() ? 200 : 5000;
+const layouts = new Map<string, ReturnType<typeof layoutWithElk>>();
+
 /**
  * Lays a node graph out for the visualiser (with ELK, left to right). Builders
  * create their nodes and edges without positions and lay the finished graph
@@ -9,7 +16,19 @@ type Graph = { nodes: any[]; edges: any[] };
  * (nodes with children) are sized to fit them, and edges get the route they're
  * drawn along (`data.route`), with room for their labels.
  */
-export const layoutNodeGraph = async <G extends Graph>(graph: G): Promise<G> => (await layoutWithElk(graph)) as unknown as G;
+export const layoutNodeGraph = async <G extends Graph>(graph: G): Promise<G> => {
+  // A build lays the same graph out on several pages (a message's docs, visualiser and schema pages):
+  // reuse the layout. Each caller gets its own copy, so it can't change the one kept.
+  const key = JSON.stringify(graph);
+  let layout = layouts.get(key);
+  if (!layout) {
+    layout = layoutWithElk(graph);
+    layouts.set(key, layout);
+    layout.catch(() => layouts.delete(key));
+    if (layouts.size > MAX_CACHED_LAYOUTS) layouts.delete(layouts.keys().next().value!);
+  }
+  return structuredClone(await layout) as unknown as G;
+};
 
 /**
  * Lays out the graphs of a levels page: level 1 (`overview`: domains, systems

package/eventcatalog/src/utils/node-graphs/node-resource.ts

@@ -0,0 +1,67 @@
+/**
+ * The catalog resource a diagram node shows, for the node types the node graphs build. Has no imports so it can
+ * be shared by the server and the browser (the visualiser's "Open in Studio", the MCP App views).
+ */
+
+// The collection each node type shows a resource of
+const NODE_COLLECTIONS: Record<string, string> = {
+  service: 'services',
+  services: 'services',
+  agent: 'agents',
+  agents: 'agents',
+  event: 'events',
+  events: 'events',
+  command: 'commands',
+  commands: 'commands',
+  query: 'queries',
+  queries: 'queries',
+  channel: 'channels',
+  channels: 'channels',
+  flow: 'flows',
+  flows: 'flows',
+  data: 'containers',
+  containers: 'containers',
+  'data-products': 'data-products',
+  domain: 'domains',
+  domains: 'domains',
+  'context-domain': 'domains',
+  'domain-group': 'domains',
+  system: 'systems',
+  systems: 'systems',
+  'system-group': 'systems',
+};
+
+// Where each node type keeps the resource it shows
+const RESOURCE_DATA_KEYS = [
+  'service',
+  'agent',
+  'message',
+  'channel',
+  'data',
+  'dataProduct',
+  'flow',
+  'entity',
+  'domain',
+  'system',
+  'custom',
+];
+
+type DiagramNode = { type?: string; data?: Record<string, unknown> };
+type ResourceDetails = { id?: unknown; version?: unknown; [key: string]: unknown };
+
+/** The resource a node shows, as in its data: the fields shown, or the catalog entry's data (if it holds the entry) */
+export const getNodeResourceDetails = (node: DiagramNode): ResourceDetails | undefined => {
+  const data = node.data ?? {};
+  const resource = RESOURCE_DATA_KEYS.map((key) => data[key]).find(Boolean) as
+    | (ResourceDetails & { data?: ResourceDetails })
+    | undefined;
+  return resource?.data ?? resource;
+};
+
+/** The catalog resource a node shows (its collection, id and version), if it shows one */
+export const getNodeCatalogResource = (node: DiagramNode): { collection: string; id: string; version?: string } | undefined => {
+  const collection = NODE_COLLECTIONS[node.type ?? ''];
+  const details = getNodeResourceDetails(node);
+  if (!collection || typeof details?.id !== 'string') return undefined;
+  return { collection, id: details.id, ...(typeof details.version === 'string' && { version: details.version }) };
+};

package/eventcatalog/src/utils/node-graphs/systems-node-graph.ts

@@ -142,7 +142,7 @@ const wrapNodesInSystemGroup = (systemNodes: any[], system: any) => {
     draggable: false,
     selectable: false,
     data: {
-      system: { name: system.data.name, version: system.data.version },
+      system: { id: system.data.id, name: system.data.name, version: system.data.version },
       // The system is the resource being viewed on its own diagram
       isFocused: true,
     },

package/eventcatalog/src/utils/page-title.ts

@@ -0,0 +1,15 @@
+import config from '@config';
+
+/** The catalog's name: `title` in eventcatalog.config.js, or EventCatalog when it has none */
+export const getCatalogTitle = (): string => config?.title?.trim() || 'EventCatalog';
+
+/**
+ * A page's title, as browser tabs and link previews show it: the page's own title, then the
+ * catalog's (`Domains | Ordering | Acme Inc`), so tabs show the page first. A page without a title
+ * of its own (the homepage) is just the catalog's.
+ */
+export const formatPageTitle = (title?: string): string => {
+  const catalogTitle = getCatalogTitle();
+  const pageTitle = title?.trim();
+  return pageTitle && pageTitle !== catalogTitle ? `${pageTitle} | ${catalogTitle}` : catalogTitle;
+};