@eventcatalog/core 3.48.4 → 4.0.0-beta.1

package/eventcatalog/src/utils/icon.ts

@@ -17,3 +17,14 @@ export function iconFieldsForResource(
   const styleIcon = data?.styles?.icon;
   return isIconPath(styleIcon) ? { leftIcon: styleIcon } : { icon: defaultIcon };
 }
+
+/**
+ * Like {@link iconFieldsForResource} but with no default icon: returns the custom
+ * `styles.icon` when one is defined, otherwise no icon at all. Used where the
+ * surrounding context (a typed section header) already conveys the resource type,
+ * so the default per-item icon would be redundant.
+ */
+export function customIconFieldsForResource(data: { styles?: { icon?: string } } | undefined): { leftIcon: string } | {} {
+  const styleIcon = data?.styles?.icon;
+  return isIconPath(styleIcon) ? { leftIcon: styleIcon } : {};
+}

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

@@ -24,9 +24,17 @@ interface Props {
   mode?: 'simple' | 'full';
   channelRenderMode?: 'flat' | 'single';
   collection?: CollectionEntry<'containers'>[];
+  layout?: boolean;
 }
 
-export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simple', channelRenderMode = 'flat' }: Props) => {
+export const getNodesAndEdges = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+  layout = true,
+}: Props) => {
   // 1. Fetch data
   const containers = await getContainers();
 
@@ -289,7 +297,9 @@ export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simpl
   });
 
   // Render the diagram in memory getting hte X and Y
-  dagre.layout(flow);
+  if (layout) {
+    dagre.layout(flow);
+  }
 
   return {
     nodes: calculatedNodes(flow, nodes),

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

@@ -13,181 +13,11 @@ import { getNodesAndEdges as getAgentsNodeAndEdges } from './agents-node-graph';
 import { getNodesAndEdges as getDataProductsNodeAndEdges } from './data-products-node-graph';
 import merge from 'lodash.merge';
 import { createVersionedMap, findInMap } from '@utils/collections/util';
-import type { Node } from '@xyflow/react';
 import { getProducersOfMessage } from '@utils/collections/services';
 import { getProducersOfMessage as getAgentProducersOfMessage } from '@utils/collections/agents';
 
 type DagreGraph = any;
 
-interface Props {
-  defaultFlow?: DagreGraph;
-  channelRenderMode?: 'single' | 'flat';
-}
-
-export const getNodesAndEdgesForDomainContextMap = async ({ defaultFlow = null }: Props) => {
-  const flow = defaultFlow ?? createDagreGraph({ ranksep: 360, nodesep: 50, edgesep: 50 });
-  let nodes = [] as any,
-    edges = [] as any;
-
-  // 1. Parallel Fetching
-  const [allDomains, services, agents, events, commands, queries] = await Promise.all([
-    getCollection('domains'),
-    getCollection('services'),
-    getCollection('agents'),
-    getCollection('events'),
-    getCollection('commands'),
-    getCollection('queries'),
-  ]);
-
-  const domains = allDomains.filter((domain) => !domain.id.includes('/versioned'));
-  const messages = [...events, ...commands, ...queries];
-
-  // 2. Build optimized maps
-  const serviceMap = createVersionedMap(services);
-  const agentMap = createVersionedMap(agents);
-  const messageMap = createVersionedMap(messages);
-
-  domains.forEach((domain, index) => {
-    const nodeId = generateIdForNode(domain);
-    const rawServices = domain.data.services ?? [];
-    const rawAgents = domain.data.agents ?? [];
-
-    // Optimized service resolution
-    const domainServices = rawServices
-      .map((service) => findInMap(serviceMap, service.id, service.version))
-      .filter((e) => e !== undefined);
-    const domainAgents = rawAgents.map((agent) => findInMap(agentMap, agent.id, agent.version)).filter((e) => e !== undefined);
-    const domainResources = [...domainServices, ...domainAgents];
-
-    // Calculate domain node size based on services
-    const servicesCount = domainResources.length;
-    const SERVICES_PER_ROW = 1;
-    const SERVICE_WIDTH = 330;
-    const SERVICE_HEIGHT = 120;
-    const PADDING = 40;
-    const TITLE_HEIGHT = 20;
-
-    const rows = Math.ceil(servicesCount / SERVICES_PER_ROW);
-    const domainWidth = SERVICE_WIDTH * SERVICES_PER_ROW;
-    const domainHeight = SERVICE_HEIGHT * rows + PADDING * 4;
-
-    // Position domains in a grid layout
-    const DOMAINS_PER_ROW = 2;
-    const rowIndex = Math.floor(index / DOMAINS_PER_ROW);
-    const colIndex = index % DOMAINS_PER_ROW;
-
-    nodes.push({
-      id: nodeId,
-      type: 'group',
-      position: {
-        x: colIndex * (domainWidth + 400),
-        y: rowIndex * (domainHeight + 300),
-      },
-      style: {
-        width: domainWidth,
-        height: domainHeight,
-        backgroundColor: 'transparent',
-        borderRadius: '8px',
-        border: '1px solid #ddd',
-        'box-shadow': '0 0 10px 0 rgba(0, 0, 0, 0.1)',
-      },
-      data: {
-        label: domain.data.name,
-        domain,
-      },
-    });
-
-    nodes.push({
-      id: `domain-context-map-title-${domain.data.name}`,
-      data: { label: `Bounded Context: ${domain.data.name}` },
-      position: { x: 0, y: 0 },
-      style: {
-        height: 20,
-        backgroundColor: 'transparent',
-        border: 'none',
-        color: 'black',
-        width: domainWidth,
-      },
-      extent: 'parent',
-      parentId: nodeId,
-      connectable: false,
-      sourcePosition: 'left',
-      targetPosition: 'right',
-      draggable: false,
-    } as Node);
-
-    // Position services in a grid within the domain
-    if (domainResources) {
-      domainResources.forEach((service, serviceIndex) => {
-        const row = Math.floor(serviceIndex / SERVICES_PER_ROW);
-        const col = serviceIndex % SERVICES_PER_ROW;
-
-        // Add spacing between services
-        const SERVICE_MARGIN = 25;
-        const xPosition = PADDING + col * (SERVICE_WIDTH + SERVICE_MARGIN) + 20;
-        const yPosition = PADDING + row * (SERVICE_HEIGHT + SERVICE_MARGIN) + TITLE_HEIGHT;
-
-        nodes.push({
-          id: generateIdForNode(service),
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: service.collection,
-          position: {
-            x: xPosition,
-            y: yPosition,
-          },
-          parentId: nodeId,
-          extent: 'parent',
-          draggable: false,
-          data: {
-            mode: 'full',
-            ...(service.collection === 'agents' ? { agent: service.data } : { service: service.data }),
-          },
-        });
-
-        // Edges
-        const rawReceives = service.data.receives ?? [];
-        const rawSends = service.data.sends ?? [];
-
-        // Optimized message resolution
-        const receives = rawReceives
-          .map((receive) => findInMap(messageMap, receive.id, receive.version))
-          .filter((msg): msg is any => !!msg); // Filter undefined
-
-        // Note: 'sends' was defined but not used in the original loop logic for edges?
-        // Based on original code, it iterates `receives`.
-
-        for (const receive of receives) {
-          const producers = [...getAgentProducersOfMessage(agents, receive), ...getProducersOfMessage(services, receive)];
-
-          for (const producer of producers) {
-            const isSameDomain = domainResources.some(
-              (domainService) => domainService.collection === producer.collection && domainService.data.id === producer.data.id
-            );
-
-            if (!isSameDomain) {
-              edges.push(
-                createEdge({
-                  id: generatedIdForEdge(producer, service),
-                  source: generateIdForNode(producer),
-                  target: generateIdForNode(service),
-                  label: getEdgeLabelForServiceAsTarget(receive),
-                  zIndex: 1000,
-                })
-              );
-            }
-          }
-        }
-      });
-    }
-  });
-
-  return {
-    nodes,
-    edges,
-  };
-};
-
 interface NodesAndEdgesProps {
   id: string;
   version: string;

package/eventcatalog/src/utils/node-graphs/system-context-node-graph.ts

@@ -0,0 +1,400 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  calculatedNodes,
+  createEdge,
+  generateIdForNode,
+  buildContextMenuForSystem,
+  DEFAULT_NODE_HEIGHT,
+} from '@utils/node-graphs/utils/utils';
+import { MarkerType } from '@xyflow/react';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+
+type DagreGraph = any;
+
+interface NodesAndEdgesProps {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+// System nodes are wider than the default to fit the system name + summary comfortably.
+const SYSTEM_NODE_WIDTH = 270;
+// Actor nodes are narrower than systems — a compact pill with an icon + name.
+const ACTOR_NODE_WIDTH = 180;
+
+type SystemActor = {
+  id: string;
+  name?: string;
+  label?: string;
+  direction?: 'inbound' | 'outbound';
+};
+
+type SystemRelationship = {
+  id: string;
+  version?: string;
+  label?: string;
+};
+
+type IncomingSystemRelationship = {
+  source: CollectionEntry<'systems'>;
+  relationship: SystemRelationship;
+};
+
+interface ContextGraphFromSeedsProps {
+  // The systems the breadth-first traversal starts from. The single-system context
+  // diagram seeds with one system; the domain-level diagram seeds with every system
+  // in the domain.
+  seedSystems: CollectionEntry<'systems'>[];
+  systemMap: Map<string, CollectionEntry<'systems'>[]>;
+  serviceMap: Map<string, CollectionEntry<'services'>[]>;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+/**
+ * Shared builder for the System Diagram.
+ *
+ * Starting from the given seed systems, we walk system relationships in both directions
+ * (breadth-first) to the systems it relates to and the systems that relate to it, then
+ * their relationships, and so on — building the reachable neighbourhood. Each system
+ * becomes a node; each relationship that has a `label` becomes a labelled edge
+ * (relationships without a label are intentionally not drawn). Actors are rendered
+ * inline and deduped across all systems.
+ */
+const buildContextGraphFromSeeds = ({
+  seedSystems,
+  systemMap,
+  serviceMap,
+  defaultFlow,
+  mode = 'simple',
+  layout = true,
+}: ContextGraphFromSeedsProps) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 280, nodesep: 80, edgesep: 50 });
+  const nodes = new Map<string, any>();
+  const edges = new Map<string, any>();
+
+  // Total messages a system handles = the sum of sends + receives across all of
+  // its services. Used for the "Messages" stat on the system node.
+  const countMessagesForSystem = (system: CollectionEntry<'systems'>) => {
+    return (system.data.services || []).reduce((total, ref) => {
+      const service = findInMap(serviceMap, ref.id, ref.version);
+      if (!service) return total;
+      return total + (service.data.sends || []).length + (service.data.receives || []).length;
+    }, 0);
+  };
+
+  // Actor node ids, tracked so they can be sized differently during layout.
+  const actorNodeIds = new Set<string>();
+  // System node ids, tracked so we can detect reciprocal system-to-system
+  // relationships and collapse them into a single double-headed edge.
+  const systemNodeIds = new Set<string>();
+  const incomingRelationshipsByTargetNodeId = new Map<string, IncomingSystemRelationship[]>();
+
+  for (const versionedSystems of systemMap.values()) {
+    for (const source of versionedSystems) {
+      const relationships = (source.data.relationships || []) as SystemRelationship[];
+
+      for (const relationship of relationships) {
+        const target = findInMap(systemMap, relationship.id, relationship.version);
+        if (!target) continue;
+
+        const targetNodeId = generateIdForNode(target);
+        const incoming = incomingRelationshipsByTargetNodeId.get(targetNodeId) || [];
+        incoming.push({ source, relationship });
+        incomingRelationshipsByTargetNodeId.set(targetNodeId, incoming);
+      }
+    }
+  }
+
+  // Add (or reuse) an actor node. Actors are inline and deduped by `actor:{id}`,
+  // so the same actor referenced from multiple systems appears once.
+  const addActorNode = (actor: SystemActor) => {
+    const nodeId = `actor-${actor.id}`;
+    if (nodes.has(nodeId)) return nodeId;
+
+    actorNodeIds.add(nodeId);
+    nodes.set(nodeId, {
+      id: nodeId,
+      type: 'context-actor',
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        name: actor.name || actor.id,
+      },
+      position: { x: 0, y: 0 },
+    });
+
+    return nodeId;
+  };
+
+  const addSystemNode = (system: CollectionEntry<'systems'>) => {
+    const nodeId = generateIdForNode(system);
+    systemNodeIds.add(nodeId);
+    if (nodes.has(nodeId)) return nodeId;
+
+    nodes.set(nodeId, {
+      id: nodeId,
+      type: 'systems',
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        system: { ...system.data },
+        // Counts of what the system groups, shown as a stats row on the node.
+        // The raw frontmatter arrays are pointer lists, so their length is the count.
+        servicesCount: (system.data.services || []).length,
+        entitiesCount: (system.data.entities || []).length,
+        containersCount: (system.data.containers || []).length,
+        messagesCount: countMessagesForSystem(system),
+        contextMenu: buildContextMenuForSystem({ id: system.data.id, version: system.data.version }),
+      },
+      position: { x: 0, y: 0 },
+    });
+
+    return nodeId;
+  };
+
+  const addSystemRelationshipEdge = ({
+    sourceNodeId,
+    targetNodeId,
+    label,
+  }: {
+    sourceNodeId: string;
+    targetNodeId: string;
+    label?: string;
+  }) => {
+    if (!label) return;
+
+    const edgeId = `${sourceNodeId}-${targetNodeId}`;
+    edges.set(
+      edgeId,
+      createEdge({
+        id: edgeId,
+        source: sourceNodeId,
+        target: targetNodeId,
+        label,
+        type: 'straight',
+        markerEnd: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+      })
+    );
+  };
+
+  // Breadth-first traversal over the relationship graph, following each system's
+  // `relationships` to other systems and reverse relationships from other systems.
+  // We visit each system once.
+  const visited = new Set<string>();
+  const queue: CollectionEntry<'systems'>[] = [...seedSystems];
+
+  while (queue.length > 0) {
+    const system = queue.shift() as CollectionEntry<'systems'>;
+    const sourceNodeId = generateIdForNode(system);
+
+    if (visited.has(sourceNodeId)) continue;
+    visited.add(sourceNodeId);
+
+    addSystemNode(system);
+
+    const relationships = (system.data.relationships || []) as SystemRelationship[];
+
+    for (const relationship of relationships) {
+      const target = findInMap(systemMap, relationship.id, relationship.version);
+      // Skip dangling targets — degrade gracefully like the other pointer types.
+      if (!target) continue;
+
+      const targetNodeId = addSystemNode(target);
+
+      // Only draw an edge when the relationship declares a label. A relationship without a
+      // label still pulls the target system into the diagram, but has no edge drawn.
+      addSystemRelationshipEdge({ sourceNodeId, targetNodeId, label: relationship.label });
+
+      if (!visited.has(targetNodeId)) {
+        queue.push(target);
+      }
+    }
+
+    const incomingRelationships = incomingRelationshipsByTargetNodeId.get(sourceNodeId) || [];
+    for (const { source, relationship } of incomingRelationships) {
+      const incomingSourceNodeId = addSystemNode(source);
+
+      // Preserve relationship direction: the referring system remains the edge source,
+      // even though this traversal discovered it from the target side.
+      addSystemRelationshipEdge({
+        sourceNodeId: incomingSourceNodeId,
+        targetNodeId: sourceNodeId,
+        label: relationship.label,
+      });
+
+      if (!visited.has(incomingSourceNodeId)) {
+        queue.push(source);
+      }
+    }
+
+    // Actors that interact with this system. Each becomes an actor node with an
+    // edge whose direction depends on `direction` (inbound = actor -> system,
+    // outbound = system -> actor). Actors don't pull other systems into the graph.
+    const actors = (system.data.actors || []) as SystemActor[];
+
+    for (const actor of actors) {
+      const actorNodeId = addActorNode(actor);
+      const direction = actor.direction || 'inbound';
+      const source = direction === 'inbound' ? actorNodeId : sourceNodeId;
+      const target = direction === 'inbound' ? sourceNodeId : actorNodeId;
+
+      const edgeId = `${source}-${target}`;
+      if (edges.has(edgeId)) continue;
+
+      edges.set(
+        edgeId,
+        createEdge({
+          id: edgeId,
+          source,
+          target,
+          label: actor.label,
+          type: 'straight',
+          markerEnd: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+        })
+      );
+    }
+  }
+
+  // Collapse reciprocal system-to-system relationships. When system A relates to B
+  // and B also relates back to A, we'd otherwise draw two parallel edges. Instead we
+  // keep a single edge with arrowheads on both ends. Each direction's label is
+  // preserved (joined when they differ). Only system↔system edges are merged — actor
+  // edges are left untouched.
+  const mergedEdgeKeys = new Set<string>();
+  for (const edge of Array.from(edges.values())) {
+    if (mergedEdgeKeys.has(edge.id)) continue;
+    if (!systemNodeIds.has(edge.source) || !systemNodeIds.has(edge.target)) continue;
+
+    const reverseId = `${edge.target}-${edge.source}`;
+    const reverse = edges.get(reverseId);
+    if (!reverse || reverseId === edge.id) continue;
+
+    // Merge the two labels, keeping a single value when they match.
+    const labels = [edge.label, reverse.label].filter(Boolean);
+    const mergedLabel = labels.length > 1 && labels[0] !== labels[1] ? labels.join(' / ') : labels[0];
+
+    edges.set(edge.id, {
+      ...edge,
+      label: mergedLabel,
+      markerStart: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+    });
+    edges.delete(reverseId);
+    mergedEdgeKeys.add(edge.id);
+    mergedEdgeKeys.add(reverseId);
+  }
+
+  // Lay the graph out
+  nodes.forEach((node) =>
+    flow.setNode(node.id, {
+      width: actorNodeIds.has(node.id) ? ACTOR_NODE_WIDTH : SYSTEM_NODE_WIDTH,
+      height: DEFAULT_NODE_HEIGHT,
+    })
+  );
+  edges.forEach((edge) => flow.setEdge(edge.source, edge.target));
+
+  if (layout) {
+    dagre.layout(flow);
+  }
+
+  return {
+    nodes: calculatedNodes(flow, Array.from(nodes.values())),
+    edges: [...edges.values()],
+  };
+};
+
+/**
+ * Builds the System Diagram for a single system, seeding the traversal from
+ * that system and walking its relationships and actors outward.
+ */
+export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simple', layout = true }: NodesAndEdgesProps) => {
+  const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  const rootSystem = findInMap(systemMap, id, version);
+
+  // Nothing found...
+  if (!rootSystem) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems: [rootSystem], systemMap, serviceMap, defaultFlow, mode, layout });
+};
+
+/**
+ * Builds the System Diagram for a whole domain: seeds the traversal with every
+ * system the domain declares, then walks their relationships and actors. The result is
+ * the domain's systems plus any related systems they point at (or that point at them),
+ * with actors rendered inline — giving a single context view across the domain.
+ */
+export const getNodesAndEdgesForDomainSystems = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  layout = true,
+}: NodesAndEdgesProps) => {
+  const [allDomains, allSystems, allServices] = await Promise.all([
+    getCollection('domains'),
+    getCollection('systems'),
+    getCollection('services'),
+  ]);
+  const domainMap = createVersionedMap(allDomains);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  const domain = findInMap(domainMap, id, version);
+
+  // Nothing found, or the domain has no systems to seed from.
+  if (!domain) {
+    return { nodes: [], edges: [] };
+  }
+
+  const seedSystems = (domain.data.systems || [])
+    .map((ref: { id: string; version?: string }) => findInMap(systemMap, ref.id, ref.version))
+    .filter((system): system is CollectionEntry<'systems'> => !!system);
+
+  if (seedSystems.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+};
+
+interface AllSystemsProps {
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+/**
+ * Builds a global System Context Map for the whole catalog: every system becomes a
+ * seed, so the traversal draws all systems, the relationships between them, and the
+ * actors around them — a single map of how every system in the catalog relates.
+ */
+export const getNodesAndEdgesForAllSystems = async ({ defaultFlow, mode = 'simple', layout = true }: AllSystemsProps = {}) => {
+  const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  // Seed with the latest version of every system. `systemMap` sorts each entry so
+  // index [0] is the latest, which avoids drawing every historical version.
+  const seedSystems = Array.from(systemMap.values())
+    .map((versions) => versions[0])
+    .filter((system): system is CollectionEntry<'systems'> => !!system);
+
+  if (seedSystems.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+};