@eventcatalog/core 5.4.2 → 5.5.0

package/eventcatalog/src/features/mcp/mcp-scoped-tools.ts

@@ -12,6 +12,7 @@ import {
   paginate,
 } from '@features/tools/catalog-tools';
 import type { McpScope } from './mcp-scope';
+import type { ArchitectureDiagramDetail } from '@utils/node-graphs/architecture-diagram-types';
 
 const notFound = (collection: string, id: string, version?: string) => ({
   error: `Resource not found: ${collection}/${id}${version ? ` (${version})` : ''}`,
@@ -186,7 +187,7 @@ export function createScopedCatalogTools(scope: McpScope) {
       resourceId: string;
       resourceVersion?: string;
       resourceCollection: string;
-      detail?: 'overview' | 'full';
+      detail?: ArchitectureDiagramDetail;
     }) {
       const entry = scope.find(params.resourceCollection, params.resourceId, params.resourceVersion);
       if (!entry) return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);

package/eventcatalog/src/features/mcp/mcp-server.ts

@@ -11,6 +11,7 @@ import { McpScopeNotFoundError, resolveMcpScope, type McpScope, type McpScopeKin
 import { getArchitectureDiagramView } from '@utils/node-graphs/architecture-diagram';
 import type {
   ArchitectureDiagramCollection,
+  ArchitectureDiagramDetail,
   ArchitectureDiagramView,
   Graph,
 } from '@utils/node-graphs/architecture-diagram-types';
@@ -30,7 +31,7 @@ const loadViewerView = getMcpAppViewLoader('viewer');
 
 const SHOW_RESOURCE_DESCRIPTION = [
   "Show the user a resource in EventCatalog's interactive viewer. Pick what to show with view:",
-  '"architecture" shows an architecture diagram of a domain, system, service, agent, event, command, query, flow, data store or data product: what it connects to, what it publishes and consumes, and the systems and domains around it. Use it whenever the user wants to see or understand how something works or fits together, e.g. "show me how the Order Service works", "how does the Ordering domain fit together", "what does Payments talk to", or asks for a diagram, map or visual of something. Prefer it over drawing your own diagram. For domains and systems, pass detail "overview" for just the domains, systems and their relationships, or "full" (default) to include services, messages and channels.',
+  '"architecture" shows an architecture diagram of a domain, system, service, agent, event, command, query, flow, data store or data product: what it connects to, what it publishes and consumes, and the systems and domains around it. Use it whenever the user wants to see or understand how something works or fits together, e.g. "show me how the Order Service works", "how does the Ordering domain fit together", "what does Payments talk to", or asks for a diagram, map or visual of something. Prefer it over drawing your own diagram. Pick the level with detail: "overview" for just the domains, systems and their relationships (domains and systems), "services" for services and data stores without messages and channels, or "full" (default) to include messages and channels.',
   '"schema" shows the schema of a message (event, command or query) or other resource: its properties, types, descriptions and which ones are required. Use it whenever the user wants to see or understand a schema or payload, e.g. "show me the schema for OrderCreated", "what fields does PlaceOrder have", "what does the OrderShipped payload look like".',
   'Clients that support MCP Apps show one viewer and switch it to each thing you show, so call this again to show the user something else. The result also contains what is shown (the diagram as Mermaid in mermaidCode, or the schema code) so you can understand it.',
   'When the client shows the viewer, do not redraw the diagram or print the whole schema again in your reply: explain it and point out what matters. Otherwise, show the user the mermaidCode or the relevant parts of the schema code.',
@@ -389,6 +390,7 @@ function createMcpServer(
     resourceId: string;
     resourceVersion: string;
     visualiserUrl: string;
+    detail?: ArchitectureDiagramDetail;
   }): Promise<ArchitectureDiagramPayload> => ({
     resource: {
       collection: diagram.resourceCollection,
@@ -405,6 +407,7 @@ function createMcpServer(
         version: diagram.resourceVersion,
       })
     ),
+    ...(diagram.detail ? { detail: diagram.detail } : {}),
   });
 
   // The resource's schemas, parsed for the view's JSON Schema, Avro and Protobuf viewers
@@ -455,7 +458,7 @@ function createMcpServer(
     resourceId: string;
     resourceVersion?: string;
     resourceCollection: string;
-    detail?: 'overview' | 'full';
+    detail?: ArchitectureDiagramDetail;
   };
 
   const loadArchitectureView = async ({ view, ...params }: ResourceViewParams) => {
@@ -470,7 +473,8 @@ function createMcpServer(
       label: `the architecture diagram for ${result.resourceCollection}/${result.resourceId}`,
       getPayload: async (): Promise<ViewerPayload> => ({
         view: 'architecture',
-        diagram: await getArchitectureDiagramPayload(result),
+        // Opens at the level asked for, as the Mermaid the model gets is; without one, at the diagram's default
+        diagram: await getArchitectureDiagramPayload({ ...result, detail: params.detail }),
       }),
     };
   };
@@ -517,12 +521,9 @@ function createMcpServer(
       description: SHOW_RESOURCE_DESCRIPTION,
       input: {
         ...resourceViewInput,
-        detail: z
-          .enum(['overview', 'full'])
+        detail: catalogTools.architectureDiagramDetailSchema
           .optional()
-          .describe(
-            'For view "architecture" of domains and systems: "overview" shows only domains, systems and their relationships; "full" (default) also shows services, messages and channels'
-          ),
+          .describe(`For view "architecture": ${catalogTools.architectureDiagramDetailSchema.description}`),
       },
     },
     viewTool: {

package/eventcatalog/src/features/studio/components/StudioDesigner.tsx

@@ -97,6 +97,7 @@ import {
   type HotspotFields,
   type HotspotSeverity,
   type HotspotSpot,
+  RemeasureHandles,
 } from '@eventcatalog/visualiser/studio';
 import { X } from 'lucide-react';
 import type { CatalogRelation, CatalogResource } from '../catalog-resources';
@@ -1751,6 +1752,7 @@ function Canvas({
                     maxZoom={2}
                   >
                     <DiagramBackground />
+                    <RemeasureHandles />
                     {/* Above the selected node's top right corner: its details, to edit them */}
                     {toEdit && <EditButton nodeId={toEdit.id} locked={locked} onClick={editSelected} />}
                     <LegendPanel legend={legend} hiddenKeys={hiddenLegendKeys} onLegendClick={toggleLegendKey} />

package/eventcatalog/src/features/tools/catalog-tools.ts

@@ -12,10 +12,11 @@ import fs from 'node:fs';
 import { getArchitectureDiagramGraph } from '@utils/node-graphs/architecture-diagram';
 import {
   ARCHITECTURE_DIAGRAM_COLLECTIONS,
+  ARCHITECTURE_DIAGRAM_DETAILS,
   isArchitectureDiagramCollection,
   type ArchitectureDiagramDetail,
 } from '@utils/node-graphs/architecture-diagram-types';
-import { convertToMermaid } from '@utils/node-graphs/export-mermaid';
+import { convertToMermaid } from '@eventcatalog/visualiser/layout';
 import { glob } from 'glob';
 import path from 'node:path';
 import {
@@ -201,6 +202,12 @@ export const resourceCollectionSchema = z.enum([
 
 export const visualiserCollectionSchema = z.enum(ARCHITECTURE_DIAGRAM_COLLECTIONS);
 
+export const architectureDiagramDetailSchema = z
+  .enum(ARCHITECTURE_DIAGRAM_DETAILS)
+  .describe(
+    'The level of the diagram, as on its Diagram page: "overview" (L1) shows only domains, systems and their relationships (domains and systems only); "services" (L2) shows services and data stores without messages and channels; "full" (L3, default) also shows messages and channels'
+  );
+
 // ============================================
 // Tool implementations (core logic)
 // ============================================

package/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/index.astro

@@ -31,6 +31,7 @@ const {
       collection={`${collection}-entities`}
       title={`${props.data.name} (v${props.data.version}) - Entity Diagram`}
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version={props.data.version}
       linksToVisualiser={false}

package/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro

@@ -33,6 +33,7 @@ const {
       collection={collection}
       title={`${props.data.name} (v${props.data.version})`}
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version={props.data.version}
       linksToVisualiser={false}

package/eventcatalog/src/pages/visualiser/_mermaid-route.ts

@@ -4,12 +4,17 @@
  *
  * Domains and systems have their own routes next to their Diagram pages
  * (visualiser/domains/[id]/[version]), which would otherwise handle these requests first.
+ * Their levels are served at /visualiser/{domains|systems}/{id}/{version}/{overview|services}.mermaid.
  */
 import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
 import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
 import { getArchitectureDiagramGraph } from '@utils/node-graphs/architecture-diagram';
-import { isArchitectureDiagramCollection } from '@utils/node-graphs/architecture-diagram-types';
-import { convertToMermaid } from '@utils/node-graphs/export-mermaid';
+import {
+  ARCHITECTURE_DIAGRAM_DETAILS,
+  isArchitectureDiagramCollection,
+  type ArchitectureDiagramDetail,
+} from '@utils/node-graphs/architecture-diagram-types';
+import { convertToMermaid } from '@eventcatalog/visualiser/layout';
 import type { PageTypes } from '@types';
 
 export type MermaidDiagramType =
@@ -34,7 +39,35 @@ export async function getMermaidDiagramPaths(types: MermaidDiagramType[]) {
   );
 }
 
-export async function createMermaidDiagramResponse({ type, id, version }: { type?: string; id?: string; version?: string }) {
+/** Levels served at /visualiser/{domains|systems}/{id}/{version}/{level}.mermaid ({version}.mermaid is the full diagram) */
+export const MERMAID_LEVELS = ['overview', 'services'] as const satisfies ArchitectureDiagramDetail[];
+
+const LEVEL_DESCRIPTIONS: Record<ArchitectureDiagramDetail, string> = {
+  overview: 'L1 overview (domains, systems and their relationships)',
+  services: 'L2 services and data stores',
+  full: 'L3 full (services, messages and channels)',
+};
+
+/** Every version of each domain or system with each level, for building their Mermaid files in static builds */
+export async function getMermaidLevelPaths(type: 'domains' | 'systems') {
+  const paths = await getMermaidDiagramPaths([type]);
+  return paths.flatMap(({ id, version }) => MERMAID_LEVELS.map((level) => ({ params: { id, version, level } })));
+}
+
+const isMermaidDetail = (detail: string): detail is ArchitectureDiagramDetail =>
+  (ARCHITECTURE_DIAGRAM_DETAILS as readonly string[]).includes(detail);
+
+export async function createMermaidDiagramResponse({
+  type,
+  id,
+  version,
+  detail = 'full',
+}: {
+  type?: string;
+  id?: string;
+  version?: string;
+  detail?: string;
+}) {
   if (!type || !id || !version || !isVisualiserEnabled()) {
     return new Response('Not found', { status: 404 });
   }
@@ -44,9 +77,18 @@ export async function createMermaidDiagramResponse({ type, id, version }: { type
     return new Response(`Unsupported type: ${type}`, { status: 400 });
   }
 
+  if (!isMermaidDetail(detail)) {
+    return new Response('Not found', { status: 404 });
+  }
+
   try {
-    // Built the same way as the resource's Diagram page
-    const { nodes, edges } = await getArchitectureDiagramGraph({ collection: type, id, version });
+    // Built the same way as the resource's Diagram page, at the level asked for
+    const { nodes, edges } = await getArchitectureDiagramGraph({
+      collection: type,
+      id,
+      version,
+      ...(detail !== 'full' && { detail }),
+    });
 
     if (!nodes || nodes.length === 0) {
       return new Response('No diagram data available', { status: 404 });
@@ -60,6 +102,7 @@ export async function createMermaidDiagramResponse({ type, id, version }: { type
     // Add header comment with metadata
     const header = `%% EventCatalog Mermaid Diagram
 %% Resource: ${type}/${id} (v${version})
+%% Level: ${LEVEL_DESCRIPTIONS[detail]}
 %% Generated: ${new Date().toISOString()}
 
 `;

package/eventcatalog/src/pages/visualiser/designs/[id]/index.astro

@@ -34,6 +34,7 @@ const { data } = props;
       title={data.name}
       client:only="react"
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       isChatEnabled={isChatEnabled}
     />

package/eventcatalog/src/pages/visualiser/domains/[id]/[version]/[level].mermaid.ts

@@ -0,0 +1,18 @@
+/**
+ * API endpoint to return mermaid diagram code for a level of a domain diagram
+ * URL: /visualiser/domains/{id}/{version}/{overview|services}.mermaid
+ *
+ * `overview` is level 1 (domains, systems and their relationships) and `services` level 2
+ * (services and data stores), as on the Diagram page. {version}.mermaid is the full diagram (level 3).
+ */
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { isAuthEnabled } from '@utils/feature';
+import { createMermaidDiagramResponse, getMermaidLevelPaths } from '../../../_mermaid-route';
+
+// Prerender static pages when auth is disabled, use SSR when auth is enabled
+export const prerender = !isAuthEnabled();
+
+export const getStaticPaths: GetStaticPaths = () => getMermaidLevelPaths('domains');
+
+export const GET: APIRoute = async ({ params }) =>
+  createMermaidDiagramResponse({ type: 'domains', id: params.id, version: params.version, detail: params.level });

package/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro

@@ -31,6 +31,7 @@ const {
       collection={`${collection}-entities`}
       title={`${props.data.name} (v${props.data.version}) - Entity Diagram`}
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version={props.data.version}
       linksToVisualiser={false}

package/eventcatalog/src/pages/visualiser/domains/[id]/[version]/index.astro

@@ -32,6 +32,7 @@ const {
       overview={{ label: 'domains it talks to' }}
       title={`${props.data.name} (v${props.data.version})`}
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version={props.data.version}
       linksToVisualiser={false}

package/eventcatalog/src/pages/visualiser/system-context-map/index.astro

@@ -19,6 +19,7 @@ const id = 'system-context-map';
       collection="system-context-map"
       title="System context map"
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version="1.0.0"
       linksToVisualiser={false}

package/eventcatalog/src/pages/visualiser/systems/[id]/[version]/[level].mermaid.ts

@@ -0,0 +1,18 @@
+/**
+ * API endpoint to return mermaid diagram code for a level of a system diagram
+ * URL: /visualiser/systems/{id}/{version}/{overview|services}.mermaid
+ *
+ * `overview` is level 1 (domains, systems and their relationships) and `services` level 2
+ * (services and data stores), as on the Diagram page. {version}.mermaid is the full diagram (level 3).
+ */
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { isAuthEnabled } from '@utils/feature';
+import { createMermaidDiagramResponse, getMermaidLevelPaths } from '../../../_mermaid-route';
+
+// Prerender static pages when auth is disabled, use SSR when auth is enabled
+export const prerender = !isAuthEnabled();
+
+export const getStaticPaths: GetStaticPaths = () => getMermaidLevelPaths('systems');
+
+export const GET: APIRoute = async ({ params }) =>
+  createMermaidDiagramResponse({ type: 'systems', id: params.id, version: params.version, detail: params.level });

package/eventcatalog/src/pages/visualiser/systems/[id]/[version]/index.astro

@@ -32,6 +32,7 @@ const {
       overview={{ label: 'system context' }}
       title={`${props.data.name} (v${props.data.version})`}
       mode="full"
+      syncRenderModeWithUrl
       linkTo="visualiser"
       version={props.data.version}
       linksToVisualiser={false}

package/eventcatalog/src/utils/node-graphs/architecture-diagram-types.ts

@@ -21,7 +21,13 @@ export type ArchitectureDiagramCollection = (typeof ARCHITECTURE_DIAGRAM_COLLECT
 export const isArchitectureDiagramCollection = (collection: string): collection is ArchitectureDiagramCollection =>
   (ARCHITECTURE_DIAGRAM_COLLECTIONS as readonly string[]).includes(collection);
 
-export type ArchitectureDiagramDetail = 'overview' | 'full';
+/**
+ * The levels of a diagram, as on the Diagram page's toolbar: L1 `overview` (domains, systems and their
+ * relationships), L2 `services` (services and data stores, without messages and channels) and L3 `full`.
+ */
+export const ARCHITECTURE_DIAGRAM_DETAILS = ['overview', 'services', 'full'] as const;
+
+export type ArchitectureDiagramDetail = (typeof ARCHITECTURE_DIAGRAM_DETAILS)[number];
 
 export type Graph = { nodes: any[]; edges: any[] };
 

package/eventcatalog/src/utils/node-graphs/architecture-diagram.ts

@@ -4,6 +4,7 @@
  * diagram tool used by AI Chat and the MCP server, so they show the same thing.
  */
 import config from '@config';
+import { hideMessageNodes } from '@eventcatalog/visualiser/layout';
 import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
 import { getNodesAndEdges as getNodesAndEdgesForAgent } from '@utils/node-graphs/agents-node-graph';
 import {
@@ -79,6 +80,8 @@ export async function getArchitectureDiagramGraph({
 }): Promise<Graph> {
   const view = await getArchitectureDiagramView(resource);
   // A domain without systems or subdomains has no level 1, so it shows the full diagram
-  const graph = detail === 'overview' && view.overview ? view.overview : view;
-  return { nodes: graph.nodes, edges: graph.edges };
+  if (detail === 'overview' && view.overview) return { nodes: view.overview.nodes, edges: view.overview.edges };
+  // Level 2: as laid out for domains and systems, otherwise the diagram without its messages and channels
+  if (detail === 'services') return view.hiddenMessages ?? hideMessageNodes(view.nodes, view.edges);
+  return { nodes: view.nodes, edges: view.edges };
 }

package/eventcatalog/src/utils/node-graphs/compact-visualiser-graph.ts

@@ -34,6 +34,8 @@ const RESOURCE_DATA_KEYS = [
   'schemas',
   'properties',
   'aggregateRoot',
+  // An entity's identifier, its primary key in the Mermaid export
+  'identifier',
   'sidebar',
 ] as const;