@eventcatalog/core 5.4.2 → 5.5.1

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

@@ -93,7 +93,7 @@ export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.
       if ('error' in result) return errorResult(result);
       return {
         // The model reads the text; hosts that support MCP Apps show the view from `_meta`
-        content: [{ type: 'text' as const, text: JSON.stringify(result.forModel, null, 2) }],
+        content: [{ type: 'text' as const, text: JSON.stringify(result.forModel) }],
         ...(loadView && {
           _meta: {
             [app.metaKey]: await result.getPayload(),

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.',
@@ -47,7 +48,8 @@ type McpServerOptions = {
 
 const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
 
-// Helper to create consistent MCP tool handlers with error handling
+// Helper to create consistent MCP tool handlers with error handling. Results are compact JSON: indenting them costs
+// the model about a fifth more tokens for nothing
 function createToolHandler<T>(fn: (params: T) => Promise<any>, errorMessage: string) {
   return async (params: T) => {
     try {
@@ -61,7 +63,7 @@ function createToolHandler<T>(fn: (params: T) => Promise<any>, errorMessage: str
       }
 
       return {
-        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
       };
     } catch (error) {
       return {
@@ -389,6 +391,7 @@ function createMcpServer(
     resourceId: string;
     resourceVersion: string;
     visualiserUrl: string;
+    detail?: ArchitectureDiagramDetail;
   }): Promise<ArchitectureDiagramPayload> => ({
     resource: {
       collection: diagram.resourceCollection,
@@ -405,6 +408,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 +459,7 @@ function createMcpServer(
     resourceId: string;
     resourceVersion?: string;
     resourceCollection: string;
-    detail?: 'overview' | 'full';
+    detail?: ArchitectureDiagramDetail;
   };
 
   const loadArchitectureView = async ({ view, ...params }: ResourceViewParams) => {
@@ -470,7 +474,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 +522,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: {
@@ -664,7 +666,7 @@ function createMcpServer(
         try {
           const result = await execute(params);
           return {
-            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+            content: [{ type: 'text' as const, text: JSON.stringify(result) }],
           };
         } catch (error) {
           return {
@@ -839,7 +841,7 @@ function createMcpServer(
           contents: [
             {
               uri: uri.href,
-              text: JSON.stringify({ ...(scope && { scope: scope.ref }), resources: allResources }, null, 2),
+              text: JSON.stringify({ ...(scope && { scope: scope.ref }), resources: allResources }),
               mimeType: 'application/json',
             },
           ],

package/eventcatalog/src/features/mcp/schema-viewer.ts

@@ -3,7 +3,7 @@ import { getLanguageForHighlight } from '@components/SchemaExplorer/utils';
 import { getSchemaExtensionForFormat } from '@utils/collections/schemas';
 import type { SchemaViewerSchema } from './apps/schema-viewer/shared';
 
-type SchemaToolResult = { name?: string; format?: string; url?: string; code: string };
+type SchemaToolResult = { name?: string; format?: string; path?: string; code: string };
 
 /**
  * The schemas returned by getSchemaForResource, ready for the schema viewer: parsed for its Properties tab
@@ -12,11 +12,11 @@ type SchemaToolResult = { name?: string; format?: string; url?: string; code: st
 export const toSchemaViewerSchemas = (schemas: SchemaToolResult[]): SchemaViewerSchema[] =>
   schemas.map((schema) => {
     // Schemas in the schemas collection have a format (jsonschema, avro, protobuf), others a file extension
-    const format = schema.format ?? schema.url?.split('.').pop() ?? '';
+    const format = schema.format ?? schema.path?.split('.').pop() ?? '';
     const extension = getSchemaExtensionForFormat(format);
     return {
       ...parseSchemaForViewer(extension, schema.code),
-      ...(schemas.length > 1 && { name: schema.name ?? schema.url?.split('/').pop() ?? format }),
+      ...(schemas.length > 1 && { name: schema.name ?? schema.path?.split('/').pop() ?? format }),
       format,
       language: getLanguageForHighlight(extension),
       code: schema.code,

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/studio/server/canvas-mcp.ts

@@ -52,7 +52,7 @@ const CANVAS_ICON_SVG =
 const CANVAS_ICON = { src: `data:image/svg+xml;base64,${btoa(CANVAS_ICON_SVG)}`, mimeType: 'image/svg+xml', sizes: ['20x20'] };
 
 const text = (value: unknown, isError = false) => ({
-  content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+  content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value) }],
   ...(isError && { isError }),
 });
 

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

@@ -4,18 +4,19 @@
  */
 import { getCollection } from 'astro:content';
 import { z } from 'zod';
-import { getSchemasFromResource, getSchemaFormatFromURL } from '@utils/collections/schemas';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+import { getSchemaFormatFromURL } from '@utils/collections/schemas';
+import { getItemsFromCollectionByIdAndSemverOrLatest, processSpecifications, versionMatches } from '@utils/collections/util';
 import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
 import { getAbsoluteFilePathForAstroFile } from '@utils/files';
 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)
 // ============================================
@@ -273,6 +280,74 @@ export async function getResource(params: { collection: string; id: string; vers
 
 type MessagePointer = { id: string; version?: string };
 
+type MessageEntry = { collection: string; data: { id: string; version: string } };
+
+/** Resources that send and receive messages, and the collections that hold them */
+const MESSAGING_COLLECTIONS = ['services', 'agents', 'domains'] as const;
+
+/** Old versions live in a versioned folder: what they send and receive is history, not the catalog today */
+const isLatestVersion = (entry: { filePath?: string }) => !entry.filePath?.includes('versioned');
+
+/**
+ * Whether a sends/receives pointer points at this version of a message, as on the message's pages: one without a
+ * version (or "latest") points at the latest version only; others match exactly, by semver range or by x-pattern (1.x)
+ */
+const pointsAtMessage = (pointer: MessagePointer, message: MessageEntry, latestVersion: string) => {
+  if (pointer.id !== message.data.id) return false;
+  if (!pointer.version || pointer.version === 'latest') return message.data.version === latestVersion;
+  return versionMatches(message.data.version, pointer.version);
+};
+
+/** The services, agents and domains (latest versions) that send (or receive) this version of a message */
+const getResourcesThat = async (direction: 'sends' | 'receives', message: MessageEntry) => {
+  const [latestMessage, ...collections] = await Promise.all([
+    findEntry(message.collection, message.data.id),
+    ...MESSAGING_COLLECTIONS.map((collection) => getCollection(collection)),
+  ]);
+  const latestVersion = latestMessage?.data.version ?? message.data.version;
+
+  return collections
+    .flat()
+    .filter(isLatestVersion)
+    .filter((resource) =>
+      ((resource.data as any)[direction] || []).some((pointer: MessagePointer) =>
+        pointsAtMessage(pointer, message, latestVersion)
+      )
+    );
+};
+
+/**
+ * The resources a domain or system is made of, with it: its services and agents, and for a domain its systems and
+ * subdomains (and everything inside them)
+ */
+const getResourcesInside = async (container: any) => {
+  const [domains, systems, services, agents] = await Promise.all(
+    (['domains', 'systems', 'services', 'agents'] as const).map((collection) => getCollection(collection))
+  );
+  const resolve = (entries: any[], pointers: MessagePointer[] = []) =>
+    pointers
+      .map((pointer) => getItemsFromCollectionByIdAndSemverOrLatest(entries, pointer.id, pointer.version)[0])
+      .filter(Boolean);
+
+  const found = new Map<string, any>();
+  const visit = (entry: any) => {
+    const key = `${entry.collection}/${entry.data.id}`;
+    if (found.has(key)) return;
+    found.set(key, entry);
+    if (entry.collection !== 'domains' && entry.collection !== 'systems') return;
+    [
+      ...resolve(services, entry.data.services),
+      ...resolve(agents, entry.data.agents),
+      ...(entry.collection === 'domains'
+        ? [...resolve(systems, entry.data.systems), ...resolve(domains, entry.data.domains)]
+        : []),
+    ].forEach(visit);
+  };
+  visit(container);
+
+  return [...found.values()];
+};
+
 /**
  * Resolve a sends/receives pointer to the documented message it points at
  */
@@ -314,17 +389,39 @@ export async function getMessagesProducedOrConsumedByResource(params: {
     getCollection('queries'),
   ]);
   const messages = [...events, ...commands, ...queries];
+  const summary = {
+    id: resource.data.id,
+    version: resource.data.version,
+    name: resource.data.name || resource.data.id,
+    collection: params.resourceCollection,
+  };
 
-  return {
-    resource: {
-      id: resource.data.id,
-      version: resource.data.version,
-      name: resource.data.name || resource.data.id,
-      collection: params.resourceCollection,
-    },
-    sends: (resource.data.sends || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
-    receives: (resource.data.receives || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+  if (params.resourceCollection !== 'domains' && params.resourceCollection !== 'systems') {
+    return {
+      resource: summary,
+      sends: (resource.data.sends || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+      receives: (resource.data.receives || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+    };
+  }
+
+  // A domain or system sends and receives what it and everything inside it does: `by` names who, e.g. services/orders
+  const members = await getResourcesInside(resource);
+  const collect = (direction: 'sends' | 'receives') => {
+    const found = new Map<string, ReturnType<typeof resolveMessagePointer> & { by: string[] }>();
+    for (const member of members) {
+      for (const pointer of (member.data[direction] || []) as MessagePointer[]) {
+        const message = resolveMessagePointer(messages, pointer);
+        const key = `${message.collection ?? ''}/${message.id}@${message.version}`;
+        const entry = found.get(key) ?? { ...message, by: [] };
+        const by = `${member.collection}/${member.data.id}`;
+        if (!entry.by.includes(by)) entry.by.push(by);
+        found.set(key, entry);
+      }
+    }
+    return [...found.values()];
   };
+
+  return { resource: summary, sends: collect('sends'), receives: collect('receives') };
 }
 
 /**
@@ -360,15 +457,27 @@ export async function getSchemaForResource(params: { resourceId: string; resourc
     }
   }
 
-  const schema = await getSchemasFromResource(resource);
+  const files = [
+    ...(resource.data.schemaPath
+      ? [{ path: resource.data.schemaPath, format: getSchemaFormatFromURL(resource.data.schemaPath) }]
+      : []),
+    ...processSpecifications(resource.data.specifications).map((spec) => ({
+      name: spec.name,
+      path: spec.path,
+      format: spec.type,
+    })),
+  ];
+
+  // Read from beside the resource's own file (paths are relative to it); files that can't be read are left out
+  const schemas = files.flatMap((file) => {
+    try {
+      return [{ ...file, code: fs.readFileSync(getAbsoluteFilePathForAstroFile(resource.filePath ?? '', file.path), 'utf-8') }];
+    } catch {
+      return [];
+    }
+  });
 
-  if (schema.length > 0) {
-    return schema.map((schemaItem) => ({
-      url: schemaItem.url,
-      format: schemaItem.format,
-      code: fs.readFileSync(schemaItem.url, 'utf-8'),
-    }));
-  }
+  if (schemas.length > 0) return schemas;
 
   return { message: 'No schemas found for this resource' };
 }
@@ -424,8 +533,6 @@ export async function findResourcesByOwner(params: { ownerId: string }) {
  * Get resources that produce (send) a specific message
  */
 export async function getProducersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -433,21 +540,13 @@ export async function getProducersOfMessage(params: { messageId: string; message
       error: `Message not found: ${params.messageId} (${describeVersion(params.messageVersion)}) in ${params.messageCollection}`,
     };
   }
-  const messageVersion = message.data.version;
 
-  const producers = routableResources.filter((resource) => {
-    const sends = (resource.data as any).sends || [];
-    return sends.some((send: any) => {
-      const idMatch = send.id === params.messageId;
-      if (!send.version || send.version === 'latest') return idMatch;
-      return idMatch && send.version === messageVersion;
-    });
-  });
+  const producers = await getResourcesThat('sends', message);
 
   return {
     message: {
       id: params.messageId,
-      version: messageVersion,
+      version: message.data.version,
       collection: params.messageCollection,
     },
     producers: producers.map((s) => ({
@@ -504,8 +603,6 @@ export async function getC4Diagram(params: { viewId?: string }) {
  * Get resources that consume (receive) a specific message
  */
 export async function getConsumersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -513,21 +610,13 @@ export async function getConsumersOfMessage(params: { messageId: string; message
       error: `Message not found: ${params.messageId} (${describeVersion(params.messageVersion)}) in ${params.messageCollection}`,
     };
   }
-  const messageVersion = message.data.version;
 
-  const consumers = routableResources.filter((resource) => {
-    const receives = (resource.data as any).receives || [];
-    return receives.some((receive: any) => {
-      const idMatch = receive.id === params.messageId;
-      if (!receive.version || receive.version === 'latest') return idMatch;
-      return idMatch && receive.version === messageVersion;
-    });
-  });
+  const consumers = await getResourcesThat('receives', message);
 
   return {
     message: {
       id: params.messageId,
-      version: messageVersion,
+      version: message.data.version,
       collection: params.messageCollection,
     },
     consumers: consumers.map((s) => ({
@@ -545,8 +634,6 @@ export async function getConsumersOfMessage(params: { messageId: string; message
  * Returns all affected services (producers and consumers) and their owners
  */
 export async function analyzeChangeImpact(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -556,17 +643,7 @@ export async function analyzeChangeImpact(params: { messageId: string; messageVe
   }
   const messageVersion = message.data.version;
 
-  // Find producers
-  const producers = routableResources.filter((resource) => {
-    const sends = (resource.data as any).sends || [];
-    return sends.some((send: any) => send.id === params.messageId);
-  });
-
-  // Find consumers
-  const consumers = routableResources.filter((resource) => {
-    const receives = (resource.data as any).receives || [];
-    return receives.some((receive: any) => receive.id === params.messageId);
-  });
+  const [producers, consumers] = await Promise.all([getResourcesThat('sends', message), getResourcesThat('receives', message)]);
 
   // Collect all affected teams/owners
   const affectedOwners = new Set<string>();
@@ -789,19 +866,10 @@ export async function findMessageBySchemaId(params: {
     const matches = getItemsFromCollectionByIdAndSemverOrLatest(collection, params.messageId, params.messageVersion);
     const resource = matches[0];
     if (resource) {
-      // Get producers and consumers
-      const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-      const routableResources = [...services, ...agents];
-
-      const producers = routableResources.filter((resource) => {
-        const sends = (resource.data as any).sends || [];
-        return sends.some((send: any) => send.id === params.messageId);
-      });
-
-      const consumers = routableResources.filter((resource) => {
-        const receives = (resource.data as any).receives || [];
-        return receives.some((receive: any) => receive.id === params.messageId);
-      });
+      const [producers, consumers] = await Promise.all([
+        getResourcesThat('sends', resource),
+        getResourcesThat('receives', resource),
+      ]);
 
       return {
         resource: {
@@ -1258,23 +1326,23 @@ export async function getCustomDoc(params: { id: string; section?: string }) {
 
 export const toolDescriptions = {
   getResources:
-    'Use this tool to get events, agents, services, commands, queries, flows, domains, channels, entities from EventCatalog. Supports pagination via cursor and filtering by search term (searches name, id, and summary).',
+    'Use this tool to list the resources in a collection of EventCatalog (events, commands, queries, services, agents, domains, systems, flows, channels, entities, containers, data products, diagrams or ADRs). Supports pagination via cursor and filtering by search term (searches name, id, and summary).',
   getResource:
     'Use this tool to get a specific resource from EventCatalog by its id. Returns the frontmatter and markdown documentation. Omit the version to get the latest version.',
   getMessagesProducedOrConsumedByResource:
-    'Use this tool to get the messages (events, commands, queries) a service, agent or domain sends and receives. Each message is resolved to its catalog id, version, name and summary; messages that are referenced but not documented in the catalog are marked notFound. Omit the version to use the latest version of the resource.',
+    'Use this tool to get the messages (events, commands, queries) a service, agent, domain or system sends and receives. Each message is resolved to its catalog id, version, name and summary; messages that are referenced but not documented in the catalog are marked notFound. For a domain or system, this includes what the services, agents, systems and subdomains inside it send and receive, and each message lists `by`: the resources that send or receive it (e.g. services/order-service). Omit the version to use the latest version of the resource.',
   getSchemaForResource:
     'Use this tool to get the schema or specifications (openapi or asyncapi or graphql) for a resource by its id and version',
   findResourcesByOwner:
     'Use this tool to find all resources (agents, services, events, commands, etc.) owned by a specific team or user',
   getProducersOfMessage:
-    'Use this tool to find which agents or services produce (send) a specific message (event, command, or query)',
+    'Use this tool to find which services, agents or domains produce (send) a specific message (event, command, or query). Only the latest versions of those resources are included.',
   getConsumersOfMessage:
-    'Use this tool to find which agents or services consume (receive) a specific message (event, command, or query)',
+    'Use this tool to find which services, agents or domains consume (receive) a specific message (event, command, or query). Only the latest versions of those resources are included.',
   getC4Diagram:
     'Use this tool to get the C4 diagram (or likeC4) in EventCatalog. These files usually have a .c4 extension on them',
   analyzeChangeImpact:
-    'Use this tool to analyze the impact of changing a message. Returns all affected agents and services (producers and consumers), the teams that own them, and the blast radius of the change',
+    'Use this tool to analyze the impact of changing a message. Returns all affected services, agents and domains (producers and consumers), the teams that own them, and the blast radius of the change',
   explainBusinessFlow:
     'Use this tool to get detailed information about a business flow (state machine). Returns the flow definition, steps, mermaid diagram if available, and related agents and services',
   getTeams:

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 });