@eventcatalog/core 3.48.4 → 4.0.0-beta.1

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

@@ -0,0 +1,51 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} - System Context`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:name="visualiser-graph"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection="systems-context"
+      title={`${props.data.name} (v${props.data.version}) - System Context`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>

package/eventcatalog/src/stores/sidebar-store/builders/adr.ts

@@ -27,6 +27,7 @@ const firstClassResourceCollections = [
   'flows',
   'channels',
   'domains',
+  'systems',
   'users',
   'teams',
   'containers',
@@ -50,6 +51,7 @@ const getResourcesForCollection = (collection: string, context: ResourceGroupCon
     flows: context.flows,
     channels: context.channels || [],
     domains: context.domains,
+    systems: context.systems || [],
     users: context.users || [],
     teams: context.teams || [],
     containers: context.containers,
@@ -113,7 +115,7 @@ export const buildAdrNode = (adr: Adr, owners: any[], decisionMakers: any[], con
     title: adr.data.name,
     badge: 'Decision record',
     summary: adr.data.summary,
-    icon: 'BookText',
+    icon: 'ClipboardList',
     pages: [
       buildQuickReferenceSection(
         [

package/eventcatalog/src/stores/sidebar-store/builders/agent.ts

@@ -129,7 +129,9 @@ export const buildAgentNode = (
       },
       hasFlows && {
         type: 'group',
-        title: 'Flows',
+        // If the agent declares its own flows it owns them ("Flows"); otherwise it is
+        // only referenced as a step in someone else's flow ("Appears in flows").
+        title: agentFlows.length > 0 ? 'Flows' : 'Appears in flows',
         icon: 'Waypoints',
         pages: agentFlowRefs,
       },

package/eventcatalog/src/stores/sidebar-store/builders/container.ts

@@ -112,7 +112,7 @@ export const buildContainerNode = (
       },
       renderFlows && {
         type: 'group',
-        title: 'Flows',
+        title: 'Appears in flows',
         icon: 'Waypoints',
         pages: flowRefs,
         visible: flowRefs.length > 0,

package/eventcatalog/src/stores/sidebar-store/builders/data-product.ts

@@ -143,7 +143,7 @@ export const buildDataProductNode = (
       },
       renderFlows && {
         type: 'group',
-        title: 'Flows',
+        title: 'Appears in flows',
         icon: 'Waypoints',
         pages: flowRefs,
         visible: flowRefs.length > 0,

package/eventcatalog/src/stores/sidebar-store/builders/domain.ts

@@ -14,14 +14,17 @@ import {
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { pluralizeMessageType } from '@utils/collections/messages';
 import { getSpecificationsForDomain, hasUbiquitousLanguageTermsWithSubdomainsInCollection } from '@utils/collections/domains';
-import { iconFieldsForResource } from '@utils/icon';
+import { customIconFieldsForResource } from '@utils/icon';
+
+// Sort resolved collection entries A-Z by their display name (falling back to id).
+const byResourceName = (a: any, b: any) => (a.data?.name || a.data?.id || '').localeCompare(b.data?.name || b.data?.id || '');
 
 export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[], context: ResourceGroupContext): NavNode => {
   const agentsInDomain = domain.data.agents || [];
   const renderAgents = agentsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'agents');
 
   const allServicesInDomain = domain.data.services || [];
-  const servicesInDomain = allServicesInDomain.filter((service) => !(service as any).data?.externalSystem);
+  const servicesInDomain = allServicesInDomain.filter((service) => !(service as any).data?.externalSystem).sort(byResourceName);
   const externalSystemsInDomain = allServicesInDomain.filter((service) => (service as any).data?.externalSystem);
   const renderServices = servicesInDomain.length > 0 && shouldRenderSideBarSection(domain, 'services');
   const renderExternalSystems = externalSystemsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'services');
@@ -29,13 +32,25 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
   const dataProductsInDomain = domain.data['data-products'] || [];
   const renderDataProducts = dataProductsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'data-products');
 
+  const systemsInDomain = domain.data.systems || [];
+  const renderSystems = systemsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'systems');
+
+  // The domain's System Diagram only has something to show when at least one of
+  // its systems takes part in a context graph (declares relationships or actors). This
+  // mirrors the guard that generates the visualiser page, so we never link to a page
+  // that wasn't generated.
+  const hasSystemContext = systemsInDomain.some((system: any) => {
+    const data = system?.data || system;
+    return (data?.relationships || []).length > 0 || (data?.actors || []).length > 0;
+  });
+
   const subDomains = domain.data.domains || [];
   const renderSubDomains = subDomains.length > 0 && shouldRenderSideBarSection(domain, 'subdomains');
 
-  const entitiesInDomain = domain.data.entities || [];
+  const entitiesInDomain = [...(domain.data.entities || [])].sort(byResourceName);
   const renderEntities = entitiesInDomain.length > 0 && shouldRenderSideBarSection(domain, 'entities');
 
-  const domainFlows = domain.data.flows || [];
+  const domainFlows = [...(domain.data.flows || [])].sort(byResourceName);
   const hasFlows = domainFlows.length > 0;
 
   const resourceGroups = domain.data.resourceGroups || [];
@@ -62,8 +77,29 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
   // Domain-level messages (sends/receives)
   const sendsMessages = domain.data.sends || [];
   const receivesMessages = domain.data.receives || [];
+  const sortedSendsMessages = [...sendsMessages].sort(byResourceName);
+  const sortedReceivesMessages = [...receivesMessages].sort(byResourceName);
   const renderMessages = shouldRenderSideBarSection(domain, 'messages');
 
+  // The Resources page/link only makes sense when the domain actually has resources
+  // attached (services, flows, entities or its own messages). Mirrors what the page renders.
+  const hasResources =
+    servicesInDomain.length > 0 ||
+    domainFlows.length > 0 ||
+    entitiesInDomain.length > 0 ||
+    sendsMessages.length > 0 ||
+    receivesMessages.length > 0;
+
+  // The Resource Diagram renders the domain's services, agents, data products and
+  // subdomains (see domains-node-graph). Only link to it when there's something to
+  // draw — otherwise the visualiser page is empty.
+  const hasResourceDiagram =
+    servicesInDomain.length > 0 ||
+    externalSystemsInDomain.length > 0 ||
+    agentsInDomain.length > 0 ||
+    dataProductsInDomain.length > 0 ||
+    subDomains.length > 0;
+
   // Diagrams
   const domainDiagrams = domain.data.diagrams || [];
   const diagramNavItems = buildDiagramNavItems(domainDiagrams, context.diagrams);
@@ -82,11 +118,18 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
     title: domain.data.name,
     badge: 'Domain',
     summary: domain.data.summary,
-    ...iconFieldsForResource(domain.data, 'Boxes'),
+    // Domains use a custom icon when defined, otherwise none — the surrounding
+    // 'Domains' section header (and Domain badge) already convey the type, so the
+    // default Boxes glyph on every item is redundant.
+    ...customIconFieldsForResource(domain.data),
     pages: [
       buildQuickReferenceSection(
         [
           { title: 'Overview', href: buildUrl(`/docs/domains/${domain.data.id}/${domain.data.version}`) },
+          hasResources && {
+            title: 'Domain Resources',
+            href: buildUrl(`/docs/domains/${domain.data.id}/${domain.data.version}/resources`),
+          },
           renderUbiquitousLanguage && {
             title: 'Ubiquitous Language',
             href: buildUrl(`/docs/domains/${domain.data.id}/language`),
@@ -109,15 +152,23 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
             title: 'Overview',
             href: buildUrl(`/architecture/domains/${domain.data.id}/${domain.data.version}`),
           },
-          renderVisualiser && {
-            type: 'item',
-            title: 'Map',
-            href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}`),
-          },
+          renderSystems &&
+            renderVisualiser &&
+            hasSystemContext && {
+              type: 'item',
+              title: 'System Diagram',
+              href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}/systems-context`),
+            },
+          renderVisualiser &&
+            hasResourceDiagram && {
+              type: 'item',
+              title: 'Resource Diagram',
+              href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}`),
+            },
           renderEntities &&
             renderVisualiser && {
               type: 'item',
-              title: 'Entity Map',
+              title: 'Entity Diagram',
               href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}/entity-map`),
             },
         ].filter(Boolean) as ChildRef[],
@@ -159,36 +210,81 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
           })),
         ],
       },
+      renderSystems && {
+        type: 'group',
+        title: 'Systems',
+        icon: 'Group',
+        pages: systemsInDomain.map((system) => `system:${(system as any).data.id}:${(system as any).data.version}`),
+      },
       renderSubDomains && {
         type: 'group',
         title: 'Subdomains',
         icon: 'Boxes',
         pages: subDomains.map((domain) => `domain:${(domain as any).data.id}:${(domain as any).data.version}`),
       },
-      hasFlows && {
+      (renderServices ||
+        hasFlows ||
+        renderEntities ||
+        (renderMessages && (sendsMessages.length > 0 || receivesMessages.length > 0))) && {
         type: 'group',
-        title: 'Flows',
-        icon: 'Waypoints',
-        pages: domainFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
-      },
-      renderEntities && {
-        type: 'group',
-        title: 'Entities',
-        icon: 'Box',
-        pages: entitiesInDomain.map((entity) => ({
-          type: 'item',
-          title: (entity as any).data?.name || (entity as any).data.id,
-          href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
-        })),
+        title: 'Resources',
+        icon: 'Boxes',
+        // Resource type subsections are ordered A-Z by their title, and the
+        // resources within each subsection are ordered A-Z by name (sorted above).
+        pages: (
+          [
+            renderServices && {
+              type: 'group',
+              title: 'Services',
+              subtle: true,
+              icon: 'Server',
+              pages: servicesInDomain.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
+            },
+            hasFlows && {
+              type: 'group',
+              title: 'Flows',
+              subtle: true,
+              icon: 'Waypoints',
+              pages: domainFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+            },
+            renderEntities && {
+              type: 'group',
+              title: 'Entities',
+              subtle: true,
+              icon: 'Box',
+              pages: entitiesInDomain.map((entity) => ({
+                type: 'item',
+                title: (entity as any).data?.name || (entity as any).data.id,
+                href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
+              })),
+            },
+            renderMessages &&
+              sendsMessages.length > 0 && {
+                type: 'group',
+                title: 'Domain Events',
+                subtle: true,
+                icon: 'Mail',
+                pages: sortedSendsMessages.map(
+                  (message) =>
+                    `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+                ),
+              },
+            renderMessages &&
+              receivesMessages.length > 0 && {
+                type: 'group',
+                title: 'External Events',
+                subtle: true,
+                icon: 'Mail',
+                pages: sortedReceivesMessages.map(
+                  (receive) =>
+                    `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+                ),
+              },
+          ].filter(Boolean) as NavNode[]
+        ).sort((a, b) => a.title.localeCompare(b.title)) as ChildRef[],
       },
 
       ...(hasResourceGroups ? buildResourceGroupSections(resourceGroups, context) : []),
-      renderServices && {
-        type: 'group',
-        title: 'Services In Domain',
-        icon: 'Server',
-        pages: servicesInDomain.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
-      },
       renderAgents && {
         type: 'group',
         title: 'Agents In Domain',
@@ -209,24 +305,6 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
           (dataProduct) => `data-product:${(dataProduct as any).data.id}:${(dataProduct as any).data.version}`
         ),
       },
-      sendsMessages.length > 0 &&
-        renderMessages && {
-          type: 'group',
-          title: 'Domain Events',
-          icon: 'Mail',
-          pages: sendsMessages.map(
-            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
-          ),
-        },
-      receivesMessages.length > 0 &&
-        renderMessages && {
-          type: 'group',
-          title: 'External Events',
-          icon: 'Mail',
-          pages: receivesMessages.map(
-            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
-          ),
-        },
       renderOwners && buildOwnersSection(owners),
       renderRepository && buildRepositorySection(domain.data.repository as { url: string; language: string }),
       hasAttachments && buildAttachmentsSection(domain.data.attachments as any[]),

package/eventcatalog/src/stores/sidebar-store/builders/message.ts

@@ -165,7 +165,7 @@ export const buildMessageNode = (
       },
       renderFlows && {
         type: 'group',
-        title: 'Flows',
+        title: 'Appears in flows',
         icon: 'Waypoints',
         pages: flowRefs,
         visible: flowRefs.length > 0,

package/eventcatalog/src/stores/sidebar-store/builders/service.ts

@@ -115,7 +115,7 @@ export const buildServiceNode = (
           renderVisualiser &&
             hasDataStores && {
               type: 'item',
-              title: 'Data Map',
+              title: 'Data Dependency Graph',
               href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}/data`),
             },
         ].filter(Boolean) as ChildRef[],
@@ -202,7 +202,9 @@ export const buildServiceNode = (
       },
       hasFlows && {
         type: 'group',
-        title: 'Flows',
+        // If the service declares its own flows it owns them ("Flows"); otherwise it is
+        // only referenced as a step in someone else's flow ("Appears in flows").
+        title: serviceFlows.length > 0 ? 'Flows' : 'Appears in flows',
         icon: 'Waypoints',
         pages: serviceFlowRefs,
       },

package/eventcatalog/src/stores/sidebar-store/builders/shared.ts

@@ -58,6 +58,7 @@ export type ResourceGroupContext = {
   agents?: CollectionEntry<'agents'>[];
   services: CollectionEntry<'services'>[];
   domains: CollectionEntry<'domains'>[];
+  systems?: CollectionEntry<'systems'>[];
   events: CollectionEntry<'events'>[];
   commands: CollectionEntry<'commands'>[];
   queries: CollectionEntry<'queries'>[];
@@ -115,7 +116,7 @@ export const buildArchitectureDecisionsSection = (resource: AdrResource, adrs: A
   return {
     type: 'group',
     title: 'Decision Records',
-    icon: 'BookText',
+    icon: 'ClipboardList',
     pages: [...relatedAdrs].sort(byAdrName).map(getAdrNodeKey),
   };
 };

package/eventcatalog/src/stores/sidebar-store/builders/system.ts

@@ -0,0 +1,166 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
+import { customIconFieldsForResource } from '@utils/icon';
+
+// Sort resolved collection entries A-Z by their display name (falling back to id).
+const byResourceName = (a: any, b: any) => (a.data?.name || a.data?.id || '').localeCompare(b.data?.name || b.data?.id || '');
+
+export const buildSystemNode = (system: CollectionEntry<'systems'>, owners: any[], context: ResourceGroupContext): NavNode => {
+  const servicesInSystem = [...(system.data.services || [])].sort(byResourceName);
+  const renderServices = servicesInSystem.length > 0 && shouldRenderSideBarSection(system, 'services');
+
+  const flowsInSystem = [...(system.data.flows || [])].sort(byResourceName);
+  const renderFlows = flowsInSystem.length > 0 && shouldRenderSideBarSection(system, 'flows');
+
+  const entitiesInSystem = [...(system.data.entities || [])].sort(byResourceName);
+  const renderEntities = entitiesInSystem.length > 0 && shouldRenderSideBarSection(system, 'entities');
+
+  const containersInSystem = [...(system.data.containers || [])].sort(byResourceName);
+  const renderContainers = containersInSystem.length > 0 && shouldRenderSideBarSection(system, 'containers');
+
+  // The Resources page/link only makes sense when the system actually has resources
+  // attached (services, flows, entities or data stores). Mirrors what the page renders.
+  const hasResources =
+    servicesInSystem.length > 0 || flowsInSystem.length > 0 || entitiesInSystem.length > 0 || containersInSystem.length > 0;
+
+  const systemDiagrams = system.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(systemDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0 && shouldRenderSideBarSection(system, 'diagrams');
+
+  // A system that declares relationships to other systems, or actors, can be the starting
+  // point of a Context Diagram. (Systems that are only referenced by others still get a
+  // context page; here we surface the link from systems that declare something themselves.)
+  const hasRelationships = (system.data.relationships || []).length > 0 || (system.data.actors || []).length > 0;
+
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(system, 'owners');
+  const renderRepository = system.data.repository && shouldRenderSideBarSection(system, 'repository');
+  const hasAttachments = system.data.attachments && system.data.attachments.length > 0;
+
+  const renderVisualiser = isVisualiserEnabled();
+
+  const docsSection = buildResourceDocsSection(
+    'systems',
+    system.data.id,
+    system.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  return {
+    type: 'item',
+    title: system.data.name,
+    badge: 'System',
+    summary: system.data.summary,
+    // Systems use a custom icon when defined, otherwise none — the surrounding
+    // 'Systems' section header (and System badge) already convey the type, so the
+    // default Group glyph on every item is redundant.
+    ...customIconFieldsForResource(system.data),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          {
+            title: 'Overview',
+            href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}`),
+          },
+          hasResources && {
+            title: 'System Resources',
+            href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}/resources`),
+          },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(system, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Overview',
+            href: buildUrl(`/architecture/systems/${system.data.id}/${system.data.version}`),
+          },
+          renderVisualiser &&
+            hasRelationships && {
+              type: 'item',
+              title: 'Context Diagram',
+              href: buildUrl(`/visualiser/systems/${system.data.id}/${system.data.version}/context`),
+            },
+          renderVisualiser && {
+            type: 'item',
+            title: 'Resource Diagram',
+            href: buildUrl(`/visualiser/systems/${system.data.id}/${system.data.version}`),
+          },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      (renderServices || renderFlows || renderContainers) && {
+        type: 'group',
+        title: 'Resources',
+        icon: 'Boxes',
+        // Resource type subsections are ordered A-Z by their title, and the
+        // resources within each subsection are ordered A-Z by name (sorted above).
+        pages: (
+          [
+            renderServices && {
+              type: 'group',
+              title: 'Services',
+              subtle: true,
+              icon: 'Server',
+              pages: servicesInSystem.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
+            },
+            renderFlows && {
+              type: 'group',
+              title: 'Flows',
+              subtle: true,
+              icon: 'Waypoints',
+              pages: flowsInSystem.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+            },
+            renderContainers && {
+              type: 'group',
+              title: 'Data Stores',
+              subtle: true,
+              icon: 'Database',
+              pages: containersInSystem.map(
+                (container) => `container:${(container as any).data.id}:${(container as any).data.version}`
+              ),
+            },
+          ].filter(Boolean) as NavNode[]
+        ).sort((a, b) => a.title.localeCompare(b.title)) as ChildRef[],
+      },
+      renderEntities && {
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: entitiesInSystem.map((entity) => ({
+          type: 'item',
+          title: (entity as any).data?.name || (entity as any).data.id,
+          href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
+        })),
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(system.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(system.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};