@eventcatalog/core 4.12.2 → 5.0.0-beta.0

package/eventcatalog/src/{enterprise → features}/analytics/components/AnalyticsTracker.astro

@@ -1,14 +1,12 @@
 ---
 import config from '@config';
-import { isIntegrationsEnabled } from '@utils/feature';
 
 const integrations = config.integrations;
 const cloudAnalytics = config.cloud?.analytics;
-const enabled = isIntegrationsEnabled() && integrations;
-const hasProviders = enabled && (integrations?.ga4 || integrations?.gtm || integrations?.posthog);
+const hasProviders = !!(integrations?.ga4 || integrations?.gtm || integrations?.posthog);
 const debug = integrations?.debug ?? false;
 const isCloudAnalyticsEnabled = cloudAnalytics?.enabled === true && !!cloudAnalytics?.trackingId;
-const shouldRender = isCloudAnalyticsEnabled || (enabled && (hasProviders || debug));
+const shouldRender = isCloudAnalyticsEnabled || (!!integrations && (hasProviders || debug));
 
 const base = (config.base || '/').replace(/\/$/, '');
 const baseJson = JSON.stringify(base);

package/eventcatalog/src/{enterprise → features}/analytics/tracker.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 export type EventProperties = Record<string, string | number | boolean>;
 
 export interface AnalyticsAdapter {

package/eventcatalog/src/{enterprise → features}/api/catalog.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import type { APIRoute } from 'astro';
 import utils from '@eventcatalog/sdk';
 import { isSSR } from '@utils/feature';

package/eventcatalog/src/{enterprise → features}/auth/[...auth].ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import { AstroAuth } from '@utils/auth-astro/server';
 export const prerender = false;
 export const { GET, POST } = AstroAuth();

package/eventcatalog/src/{enterprise → features}/auth/middleware/middleware-auth.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 // src/middleware/auth.ts
 import type { MiddlewareHandler } from 'astro';
 import { getSession } from '@utils/auth-astro/server';

package/eventcatalog/src/{enterprise → features}/auth/middleware/middleware.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import type { MiddlewareHandler } from 'astro';
 import { authMiddleware } from './middleware-auth.ts';
 import { sequence } from 'astro:middleware';

package/eventcatalog/src/{enterprise → features}/collections/custom-pages.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import { z } from 'astro/zod';
 import { badge, ownerReference } from '../../content.config-shared-collections';
 

package/eventcatalog/src/{enterprise → features}/collections/index.ts

@@ -1,7 +1,2 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 export { customPagesSchema } from './custom-pages';
 export { resourceDocsSchema, resourceDocCategoriesSchema } from './resource-docs';

package/eventcatalog/src/{enterprise → features}/collections/resource-docs.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import { z } from 'astro/zod';
 import { badge } from '../../content.config-shared-collections';
 

package/eventcatalog/src/{enterprise → features}/custom-documentation/collection.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import { z } from 'astro/zod';
 import { badge, ownerReference } from '../../content.config-shared-collections';
 

package/eventcatalog/src/features/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro

@@ -0,0 +1,9 @@
+---
+import { getNavigationItems } from '@features/custom-documentation/utils/custom-docs';
+import CustomDocsNavWrapper from '@features/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper';
+
+const currentPath = Astro.url.pathname;
+const sidebarItems = await getNavigationItems();
+---
+
+<CustomDocsNavWrapper client:only sidebarItems={sidebarItems} currentPath={currentPath} />

package/eventcatalog/src/{enterprise → features}/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import CustomDocsNav from './';
 import type { SidebarSection } from './types';
 

package/eventcatalog/src/{enterprise → features}/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx

@@ -1,13 +1,8 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import React from 'react';
 import { buildUrl } from '@utils/url-builder';
 import type { SidebarItem } from '../types';
 import { ExternalLinkIcon } from 'lucide-react';
-import { getCustomDocsSidebarBadgeClasses } from '@enterprise/custom-documentation/utils/badge-styles';
+import { getCustomDocsSidebarBadgeClasses } from '@features/custom-documentation/utils/badge-styles';
 
 interface NestedItemProps {
   item: SidebarItem;

package/eventcatalog/src/{enterprise → features}/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import React from 'react';
 
 interface NoResultsFoundProps {

package/eventcatalog/src/{enterprise → features}/custom-documentation/components/CustomDocsNav/index.tsx

@@ -1,15 +1,10 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { ChevronDoubleDownIcon, ChevronDoubleUpIcon } from '@heroicons/react/24/outline';
 import { buildUrl } from '@utils/url-builder';
 import type { CustomDocsNavProps, SidebarSection, SidebarItem } from './types';
 import NestedItem from './components/NestedItem';
 import NoResultsFound from './components/NoResultsFound';
-import { getCustomDocsSidebarBadgeClasses } from '@enterprise/custom-documentation/utils/badge-styles';
+import { getCustomDocsSidebarBadgeClasses } from '@features/custom-documentation/utils/badge-styles';
 
 const STORAGE_KEY = 'EventCatalog:customDocsSidebarCollapsedGroups';
 const DEBOUNCE_DELAY = 300; // 300ms debounce delay

package/eventcatalog/src/{enterprise → features}/custom-documentation/components/CustomDocsNav/types.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 export interface SidebarItem {
   label: string;
   slug?: string;

package/eventcatalog/src/{enterprise/custom-documentation/pages/docs/custom/index.astro → features/custom-documentation/components/CustomDocumentationPage.astro}

@@ -11,8 +11,8 @@ import { getOwner } from '@utils/collections/owners';
 import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
 import { resourceToCollectionMap } from '@utils/collections/util';
 import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
-import { getAdjacentPages, getNavigationItems } from '@enterprise/custom-documentation/utils/custom-docs';
-import CustomDocsNav from '@enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro';
+import { getAdjacentPages, getNavigationItems } from '@features/custom-documentation/utils/custom-docs';
+import CustomDocsNav from '@features/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro';
 import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
 import ArchitectureGraph from '@components/MDX/ArchitectureGraph/ArchitectureGraph.astro';
 import CopyAsMarkdown from '@components/CopyAsMarkdown';
@@ -46,10 +46,10 @@ const resolvedNodeGraphs = await Promise.all(
       ...nodeGraph,
       collection,
       graphCollection,
-      title: nodeGraph.title ?? (hasSystems ? 'System Context Map' : undefined),
-      hrefLabel: hasSystems ? 'Open System Context Map' : 'Open in Visualiser',
+      title: nodeGraph.title ?? (hasSystems ? 'System Context Diagram' : undefined),
+      hrefLabel: hasSystems ? 'Open Diagram' : 'Open in Visualiser',
       visualiserUrl: hasSystems
-        ? buildUrl(`/visualiser/domains/${nodeGraph.id}/${nodeGraph.version}/systems-context`)
+        ? buildUrl(`/visualiser/domains/${nodeGraph.id}/${nodeGraph.version}?level=1`)
         : buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
     };
   })

package/eventcatalog/src/{enterprise → features}/custom-documentation/utils/badge-styles.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 type ThemeBadgeType = 'domain' | 'service' | 'event' | 'command' | 'query' | 'design' | 'channel' | 'default';
 
 const THEME_BADGE_CLASSES: Record<ThemeBadgeType, string> = {

package/eventcatalog/src/{enterprise → features}/custom-documentation/utils/custom-docs.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import config from '@config';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -12,7 +7,7 @@ import matter from 'gray-matter';
 // Use getCollection (which returns plain entries) instead of getEntry, which installs
 // Astro's `slug` deprecation accessor on every entry it returns. The accessor fires a
 // `console.error` on each access of `entry.data.slug`, even though our schema legitimately
-// defines `slug` as an optional user field. See packages/core/eventcatalog/src/enterprise/collections/custom-pages.ts.
+// defines `slug` as an optional user field. See packages/core/eventcatalog/src/features/collections/custom-pages.ts.
 const getCustomPagesById = async () => {
   const all = await getCollection('customPages');
   const map = new Map<string, (typeof all)[number]>();

package/eventcatalog/src/{enterprise → features}/custom-documentation/utils/docs-search.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import MiniSearch from 'minisearch';
 
 export type MarkdownChunk = {

package/eventcatalog/src/{enterprise → features}/custom-pages/routes.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import fs from 'node:fs';
 import path from 'node:path';
 

package/eventcatalog/src/{enterprise → features}/directory/user-team-directory.ts

@@ -1,6 +1,5 @@
 import type { Loader } from 'astro/loaders';
 import pc from 'picocolors';
-import { isEventCatalogScaleEnabled } from '../feature';
 import { EventCatalogStore } from '../../stores/eventcatalog-store';
 import { globWithSafeWatcher, type GlobOptions } from '../../utils/collections/glob-loader';
 
@@ -71,10 +70,6 @@ export const userTeamDirectoryLoader = ({
         return;
       }
 
-      if (!isEventCatalogScaleEnabled()) {
-        throw new Error('Directory sources require EventCatalog Scale.');
-      }
-
       const loadEntries = collection === 'users' ? 'loadUsers' : 'loadTeams';
       const syncedDirectoryStoreResources = new Map<string, DirectoryStoreResource>();
 

package/eventcatalog/src/{enterprise → features}/fields/field-extractor.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 export interface DeepSchemaField {
   path: string;
   type: string;

package/eventcatalog/src/{enterprise → features}/fields/field-indexer.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import path from 'node:path';
 import fs from 'node:fs';
 import { FieldsDatabase } from './fields-db';

package/eventcatalog/src/{enterprise → features}/fields/fields-db.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import initSqlJs, { type Database as SqlJsDatabase } from 'sql.js';
 import fs from 'node:fs';
 

package/eventcatalog/src/{enterprise → features}/fields/pages/api/fields.ts

@@ -1,11 +1,6 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import type { APIRoute } from 'astro';
 import { Hono } from 'hono';
-import { getFieldsDatabase } from '@enterprise/fields/fields-db';
+import { getFieldsDatabase } from '@features/fields/fields-db';
 import { getRuntimePaths } from '../../../../../integrations/runtime-paths.mjs';
 
 // The CLI builds the index at this same path. Shipping it with dist-only SSR

package/eventcatalog/src/{enterprise → features}/fields/pages/fields.astro

@@ -3,7 +3,6 @@
 import '@eventcatalog/visualiser/styles-core.css';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
 
 export const prerender = false;
 ---
@@ -18,6 +17,6 @@ export const prerender = false;
     class="min-h-0 overflow-hidden bg-[rgb(var(--ec-page-bg))]"
     style="--ec-fields-sidebar-width: 320px; margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1); height: calc(100dvh - 60px);"
   >
-    <FieldsExplorer client:load isScaleEnabled={isEventCatalogScaleEnabled()} />
+    <FieldsExplorer client:load />
   </main>
 </VerticalSideBarLayout>

package/eventcatalog/src/{enterprise → features}/integrations/eventcatalog-features.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import type { AstroIntegration } from 'astro';
 import fs from 'node:fs';
 import path from 'path';
@@ -13,14 +8,10 @@ import config from '../../utils/eventcatalog-config/source';
 import {
   isEventCatalogChatEnabled,
   isAuthEnabled,
-  isEventCatalogScaleEnabled,
   isEventCatalogMCPEnabled,
   isEventCatalogMCPAuthEnabled,
   isFullCatalogAPIEnabled,
   isDevMode,
-  isIntegrationsEnabled,
-  isCustomDocsEnabled,
-  isCustomPagesEnabled,
   isSSR,
 } from '../../utils/feature';
 import { getCustomPageRoutes, isApiRoute, listCustomPageFiles, resolveCustomPagesPrefix } from '../custom-pages/routes';
@@ -83,25 +74,25 @@ const configureAuthentication = (params: {
 }) => {
   params.injectRoute({
     pattern: '/api/[...auth]',
-    entrypoint: path.join(packageDirectory, 'src/enterprise/auth/[...auth].ts'),
+    entrypoint: path.join(packageDirectory, 'src/features/auth/[...auth].ts'),
   });
   params.injectRoute({
     pattern: '/auth/login',
-    entrypoint: path.join(packageDirectory, 'src/enterprise/auth/login.astro'),
+    entrypoint: path.join(packageDirectory, 'src/features/auth/login.astro'),
   });
   params.injectRoute({
     pattern: '/auth/error',
-    entrypoint: path.join(packageDirectory, 'src/enterprise/auth/error.astro'),
+    entrypoint: path.join(packageDirectory, 'src/features/auth/error.astro'),
   });
 
   params.injectRoute({
     pattern: '/unauthorized',
-    entrypoint: path.join(packageDirectory, 'src/enterprise/auth/unauthorized.astro'),
+    entrypoint: path.join(packageDirectory, 'src/features/auth/unauthorized.astro'),
   });
 
   // Add the authentication middleware
   params.addMiddleware({
-    entrypoint: path.join(packageDirectory, 'src/enterprise/auth/middleware/middleware.ts'),
+    entrypoint: path.join(packageDirectory, 'src/features/auth/middleware/middleware.ts'),
     order: 'pre',
   });
 };
@@ -115,26 +106,26 @@ export default function eventCatalogIntegration(): AstroIntegration {
         if (isEventCatalogChatEnabled()) {
           params.injectRoute({
             pattern: '/api/chat',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/ai/chat-api.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/ai/chat-api.ts'),
           });
         }
 
-        // Handle routes for MCP Server (requires SSR + Scale)
+        // Handle routes for MCP Server (requires SSR)
         if (isEventCatalogMCPEnabled()) {
           params.injectRoute({
             pattern: '/docs/mcp/[...path]',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/mcp/mcp-server.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/mcp/mcp-server.ts'),
           });
         }
 
         if (isEventCatalogMCPAuthEnabled()) {
           params.injectRoute({
             pattern: '/.well-known/oauth-protected-resource',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/mcp/oauth-protected-resource.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/mcp/oauth-protected-resource.ts'),
           });
           params.injectRoute({
             pattern: '/.well-known/oauth-protected-resource/[...path]',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/mcp/oauth-protected-resource.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/mcp/oauth-protected-resource.ts'),
           });
         }
 
@@ -143,51 +134,11 @@ export default function eventCatalogIntegration(): AstroIntegration {
           configureAuthentication(params);
         }
 
-        // Custom documentation routes (Starter/Scale plan)
-        if (isCustomDocsEnabled()) {
-          params.injectRoute({
-            pattern: '/docs/custom',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/root-index.astro'),
-          });
-          params.injectRoute({
-            pattern: '/docs/custom/[...path]',
-            entrypoint: path.join(
-              packageDirectory,
-              'src/enterprise/custom-documentation/pages/docs/custom/[...path]/index.astro'
-            ),
-          });
-          params.injectRoute({
-            pattern: '/docs/custom/[...path].mdx',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/[...path].mdx.ts'),
-          });
-        } else {
-          // Show feature page for non-paying users
-          params.injectRoute({
-            pattern: '/docs/custom',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/feature.astro'),
-          });
-        }
-
-        // Schema API routes (Scale plan)
-        if (isEventCatalogScaleEnabled()) {
-          params.injectRoute({
-            pattern: '/api/schemas/[collection]/[id]/[version]',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts'),
-          });
-          params.injectRoute({
-            pattern: '/api/schemas/services/[id]/[version]/[specification]',
-            entrypoint: path.join(
-              packageDirectory,
-              'src/enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts'
-            ),
-          });
-        }
-
         // Full catalog API route (opt-in)
         if (isFullCatalogAPIEnabled()) {
           params.injectRoute({
             pattern: '/api/catalog',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/api/catalog.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/api/catalog.ts'),
           });
         }
 
@@ -195,40 +146,31 @@ export default function eventCatalogIntegration(): AstroIntegration {
         if (isSSR()) {
           params.injectRoute({
             pattern: '/schemas/fields',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/fields/pages/fields.astro'),
+            entrypoint: path.join(packageDirectory, 'src/features/fields/pages/fields.astro'),
           });
           params.injectRoute({
             pattern: '/api/schemas/fields',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/fields/pages/api/fields.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/fields/pages/api/fields.ts'),
           });
         }
 
-        // User-defined pages and API routes (Scale plan)
-        if (isCustomPagesEnabled()) {
-          configureCustomPages(params);
-        } else if (listCustomPageFiles(customPagesDirectory).length > 0) {
-          console.warn('[EventCatalog] Custom pages require the Scale plan. The routes for your pages will not be served.');
-        }
+        // User-defined pages and API routes
+        configureCustomPages(params);
 
         // Keep routes in sync during dev — a manifest change restarts the dev
         // server so injectRoute runs again with the new file list
         writeCustomPagesManifest();
         params.addWatchFile(customPagesManifest);
 
-        // Warn if integrations are configured without Scale plan
-        if (config.integrations && !isIntegrationsEnabled()) {
-          console.warn('[EventCatalog] Integrations require the Scale plan. Analytics integrations will not be loaded.');
-        }
-
         // Dev-only routes for visualizer layout persistence
         if (isDevMode()) {
           params.injectRoute({
             pattern: '/api/dev/visualizer-layout/save',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/visualizer-layout/save.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/visualizer-layout/save.ts'),
           });
           params.injectRoute({
             pattern: '/api/dev/visualizer-layout/reset',
-            entrypoint: path.join(packageDirectory, 'src/enterprise/visualizer-layout/reset.ts'),
+            entrypoint: path.join(packageDirectory, 'src/features/visualizer-layout/reset.ts'),
           });
         }
       },

package/eventcatalog/src/features/mcp/apps/architecture-diagram/links.ts

@@ -0,0 +1,59 @@
+/**
+ * Links in the architecture diagram view. Links to a resource's Diagram page (e.g. "Focus node")
+ * open that diagram in the view; other links open EventCatalog in the MCP host.
+ */
+import {
+  isArchitectureDiagramCollection,
+  type ArchitectureDiagramCollection,
+} from '@utils/node-graphs/architecture-diagram-types';
+
+// /visualiser/{collection}/{id}/{version}, after any base path
+const DIAGRAM_PATH = /\/visualiser\/([^/]+)\/([^/]+)\/([^/]+)\/?$/;
+
+export type DiagramLink = { collection: ArchitectureDiagramCollection; id: string; version: string };
+
+/** The diagram a link opens, if it is a link to a Diagram page in this EventCatalog */
+export function parseDiagramLink(href: string, catalogUrl: string): DiagramLink | undefined {
+  let url: URL;
+  try {
+    url = new URL(href, catalogUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.origin !== new URL(catalogUrl).origin) return undefined;
+
+  const match = url.pathname.match(DIAGRAM_PATH);
+  if (!match || !isArchitectureDiagramCollection(match[1])) return undefined;
+
+  const [, collection, id, version] = match.map((part) => decodeURIComponent(part));
+  return { collection: collection as ArchitectureDiagramCollection, id, version };
+}
+
+// Links in a node's right-click menu that open the "Ask a question" modal for the node
+const ASK_LINK_PREFIX = '#ec-mcp-ask=';
+
+export const askLink = (nodeId: string) => `${ASK_LINK_PREFIX}${encodeURIComponent(nodeId)}`;
+
+/** The id of the node to ask about, if the link opens the "Ask a question" modal */
+export const parseAskLink = (href: string) =>
+  href.startsWith(ASK_LINK_PREFIX) ? decodeURIComponent(href.slice(ASK_LINK_PREFIX.length)) : undefined;
+
+type ContextMenuItem = { label: string; href: string; separator?: boolean; [key: string]: unknown };
+type GraphNode = { id: string; data?: Record<string, any> };
+
+/** Nodes with "Ask a question" first in their right-click menu, before the menu they already have */
+export function withAskMenuItem<T extends GraphNode>(nodes: T[]): Array<T & { data: { contextMenu: ContextMenuItem[] } }> {
+  return nodes.map((node) => {
+    const menu: ContextMenuItem[] = node.data?.contextMenu ?? [];
+    return {
+      ...node,
+      data: {
+        ...node.data,
+        contextMenu: [
+          { label: 'Ask a question', href: askLink(node.id) },
+          ...menu.map((item, index) => (index === 0 ? { ...item, separator: true } : item)),
+        ],
+      },
+    };
+  });
+}