@eventcatalog/core 4.9.0 → 4.10.1

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts

@@ -1,20 +1,66 @@
 // Shared utilities for NestedSideBar components
 
 export const SIDEBAR_GROUP_COLLAPSE_THRESHOLD = 5;
-const GROUP_TITLES_WITHOUT_COUNT = new Set(['Quick Reference', 'Architecture', 'Resources']);
 
+/**
+ * The user's overrides of each group's default collapse state, keyed by group id.
+ * A group is in at most one set; absence means "use the group's default".
+ */
 export type SectionCollapsePreferences = {
   expanded: Set<string>;
+  collapsed: Set<string>;
+};
+
+export const createSectionCollapsePreferences = (
+  expanded: Iterable<string> = [],
+  collapsed: Iterable<string> = []
+): SectionCollapsePreferences => ({
+  expanded: new Set(expanded),
+  collapsed: new Set(collapsed),
+});
+
+/**
+ * Whether a group shows a caret and can be toggled. Every group inside a resource's sidebar
+ * can collapse (docs-sidebar behaviour); the root catalog level stays open. An explicit
+ * `collapsed` (set via sidebar.json) overrides every other rule, including `collapsible: false`.
+ */
+export const canCollapseGroup = (isTopLevel: boolean, collapsible = true, collapsed?: boolean): boolean => {
+  if (collapsed !== undefined) return true;
+  return collapsible && !isTopLevel;
 };
 
-export const canCollapseGroup = (childCount: number, isTopLevel: boolean, collapsible = true): boolean =>
-  collapsible && !isTopLevel && childCount > SIDEBAR_GROUP_COLLAPSE_THRESHOLD;
+/**
+ * The state a group starts in before the user touches it: an explicit `collapsed` wins,
+ * otherwise long lists start collapsed and short ones start open.
+ */
+export const getDefaultCollapsedState = (childCount: number, collapsed?: boolean): boolean =>
+  collapsed ?? childCount > SIDEBAR_GROUP_COLLAPSE_THRESHOLD;
 
-export const getGroupLabel = (title: string, childCount: number): string =>
-  GROUP_TITLES_WITHOUT_COUNT.has(title) ? title : `${title} (${childCount})`;
+export const isGroupCollapsed = (
+  canCollapse: boolean,
+  groupId: string,
+  preferences: SectionCollapsePreferences,
+  defaultCollapsed = true
+): boolean => {
+  if (!canCollapse) return false;
+  if (preferences.expanded.has(groupId)) return false;
+  if (preferences.collapsed.has(groupId)) return true;
+  return defaultCollapsed;
+};
 
-export const isGroupCollapsed = (canCollapse: boolean, groupId: string, preferences: SectionCollapsePreferences): boolean => {
-  return canCollapse && !preferences.expanded.has(groupId);
+/** Flip a group's state, recording it as an override of its default. */
+export const toggleGroupCollapsed = (
+  groupId: string,
+  preferences: SectionCollapsePreferences,
+  defaultCollapsed = true
+): SectionCollapsePreferences => {
+  const next = createSectionCollapsePreferences(preferences.expanded, preferences.collapsed);
+  const isCurrentlyCollapsed = isGroupCollapsed(true, groupId, preferences, defaultCollapsed);
+  next.expanded.delete(groupId);
+  next.collapsed.delete(groupId);
+  if (isCurrentlyCollapsed) next.expanded.add(groupId);
+  else next.collapsed.add(groupId);
+  return next;
 };
 
 /**

package/eventcatalog/src/content.config.ts

@@ -1199,6 +1199,73 @@ const schemas = defineCollection({
     .extend(baseSchema.shape),
 });
 
+// Optional `sidebar.json` next to a resource's index.mdx. When present it fully
+// replaces the generated sidebar for that resource (see stores/sidebar-store/custom-sidebar.ts).
+const sidebarLinkSchema = z
+  .object({
+    title: z.string(),
+    href: z.string(),
+    icon: z.string().optional(),
+  })
+  .strict();
+
+// { "title": "Runbooks", "icon": "Siren", "collapsed": true, "pages": [...] } (custom group).
+// Groups nest: a page can itself be a group, rendered as a subsection.
+type SidebarGroupInput = {
+  title: string;
+  icon?: string;
+  collapsed?: boolean;
+  pages: Array<string | z.input<typeof sidebarLinkSchema> | SidebarGroupInput>;
+};
+const sidebarGroupSchema: z.ZodType<SidebarGroupInput> = z.lazy(() =>
+  z
+    .object({
+      title: z.string(),
+      icon: z.string().optional(),
+      collapsed: z.boolean().optional(),
+      // "$quick-reference", "[[service|OrderService@1.0.0]]", "[[doc|guides/sla]]", { title, href } or a nested group
+      pages: z.array(z.union([z.string(), sidebarLinkSchema, sidebarGroupSchema])),
+    })
+    .strict()
+);
+
+const sidebarSchema = z
+  .object({
+    $schema: z.string().optional(),
+    sections: z.array(
+      z.union([
+        // "$quick-reference" (predefined section)
+        z.string(),
+        // { "section": "$owners", "title": "Team", "collapsed": false } (predefined section, adjusted)
+        z
+          .object({
+            section: z.string(),
+            title: z.string().optional(),
+            icon: z.string().optional(),
+            collapsed: z.boolean().optional(),
+          })
+          .strict(),
+        sidebarGroupSchema,
+      ])
+    ),
+  })
+  .strict();
+
+const sidebars = defineCollection({
+  loader: globWithSafeWatcher({
+    // Anchored to the resource roots (like resourceDocCategories) so an unrelated
+    // sidebar.json elsewhere in the project — or the public/generated mirror — is ignored.
+    pattern: withIgnoredBuildArtifacts(
+      withFederatedContent([
+        '{services,events,commands,queries,flows,containers,channels,entities,data-products,systems,agents,adrs}/**/sidebar.json',
+        'domains/**/sidebar.json',
+      ])
+    ),
+    base: projectDirBase,
+  }),
+  schema: sidebarSchema,
+});
+
 export const collections = {
   events,
   commands,
@@ -1236,4 +1303,7 @@ export const collections = {
 
   // Generated from message schema references
   schemas,
+
+  // Optional per-resource sidebar overrides (sidebar.json)
+  sidebars,
 };

package/eventcatalog/src/enterprise/collections/resource-docs-utils.ts

@@ -71,6 +71,25 @@ type InferredResource = {
   resourceVersion: string;
 };
 
+const DOC_TYPE_LABELS: Record<string, string> = {
+  adrs: 'ADR',
+  runbooks: 'Runbook',
+  contracts: 'Contract',
+  troubleshooting: 'Troubleshooting',
+  guides: 'Guide',
+};
+
+/** Human label for a doc type folder, e.g. `guides` → "Guide", `release-notes` → "Release Notes". */
+export const getResourceDocTypeLabel = (type: string): string => {
+  if (DOC_TYPE_LABELS[type]) return DOC_TYPE_LABELS[type];
+  const normalized = type
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+  return normalized || 'Doc';
+};
+
 let memoryCache: ResourceDocEntry[] | null = null;
 let memoryCategoryCache: ResourceDocCategoryEntry[] | null = null;
 let memoryResourceLookupCache: Record<ResourceCollection, ResourceLookup> | null = null;

package/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro

@@ -14,9 +14,17 @@ 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 NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import ArchitectureGraph from '@components/MDX/ArchitectureGraph/ArchitectureGraph.astro';
+import { architectureGraphPortalId } from '@components/MDX/ArchitectureGraph/ArchitectureGraphPortal';
 import CopyAsMarkdown from '@components/CopyAsMarkdown';
 
-import { isVisualiserEnabled, isMarkdownDownloadEnabled, isRSSEnabled, isEventCatalogChatEnabled } from '@utils/feature';
+import {
+  isVisualiserEnabled,
+  isMarkdownDownloadEnabled,
+  isRSSEnabled,
+  isEventCatalogChatEnabled,
+  isArchitectureGraphEnabled,
+} from '@utils/feature';
 
 const props = Astro.props;
 const doc = props.data;
@@ -48,6 +56,18 @@ const resolvedNodeGraphs = await Promise.all(
   })
 );
 
+// Architecture graphs embedded via <ArchitectureGraph />. Custom docs have no
+// resource of their own, so with no `id` + `type` the whole catalog is rendered.
+const architectureGraphs = (getMDXComponentsByName(props.body, 'ArchitectureGraph') || []).map((graph: any) => ({
+  id: graph.id,
+  collection: graph.type ? resourceToCollectionMap[graph.type as keyof typeof resourceToCollectionMap] : undefined,
+  depth: graph.depth ? Number(graph.depth) : undefined,
+  lens: graph.lens,
+  search: parseMdxBooleanProp(graph.search, true),
+  legend: parseMdxBooleanProp(graph.legend, true),
+  lensPicker: parseMdxBooleanProp(graph.lensPicker, false),
+}));
+
 const { prev, next } = await getAdjacentPages(currentSlug);
 
 const ownersRaw = doc?.owners || [];
@@ -171,6 +191,31 @@ const editUrl =
               })
           }
 
+          {
+            architectureGraphs.length > 0 &&
+              architectureGraphs.map((graph: any, occurrenceIndex: number) => (
+                <ArchitectureGraph
+                  id={graph.id}
+                  collection={graph.collection}
+                  depth={graph.depth}
+                  lens={graph.lens}
+                  showSearch={graph.search}
+                  showLegend={graph.legend}
+                  showLensPicker={graph.lensPicker}
+                  portalId={architectureGraphPortalId(graph.id ?? (doc as any).id, occurrenceIndex)}
+                  href={
+                    isArchitectureGraphEnabled()
+                      ? {
+                          label: 'Open full screen',
+                          // Base URL only — the graph appends its live view state (focus, depth, lens)
+                          url: buildUrl('/visualiser/graph'),
+                        }
+                      : undefined
+                  }
+                />
+              ))
+          }
+
           <!-- Previous / Next Navigation -->
           <div class="py-8 border-t border-[rgb(var(--ec-page-border))] mt-8">
             <div class="flex flex-col sm:flex-row justify-between w-full gap-4">

package/eventcatalog/src/enterprise/fields/pages/fields.astro

@@ -1,4 +1,6 @@
 ---
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
 import { isEventCatalogScaleEnabled } from '@utils/feature';

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

@@ -24,7 +24,7 @@ const specifications = type === 'services' ? getSpecificationsForService(props)
 <VerticalSideBarLayout title={pageTitle}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
         {type === 'domains' && <DomainGrid domain={domain} client:load />}
         {type === 'systems' && <SystemGrid system={props} client:load />}
         {

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro

@@ -8,7 +8,8 @@ import CopyAsMarkdown from '@components/CopyAsMarkdown';
 import Badge from '@components/Badge.astro';
 import { buildUrl } from '@utils/url-builder';
 import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
-import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
 
@@ -51,28 +52,28 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
-          <div>
-            <div class="flex items-center">
-              <div class="flex items-center gap-2">
-                <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
-              </div>
-            </div>
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the latest-doc page ([docId]/index.astro) and the resource page. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">
+              {getResourceDocTypeLabel(props.data.type)}
+            </span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
           </div>
           {
             props.data.summary && (
-              <p class="text-base pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
+              <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
             )
           }
           {
             badges.length > 0 && (
-              <div class="flex flex-wrap gap-1.5 py-3">
+              <div class="flex flex-wrap gap-1.5 pt-4">
                 {badges.map((badge: any) => <Badge badge={badge} />)}
               </div>
             )
           }
-          <div class="pt-4">
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -80,9 +81,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -100,7 +101,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro

@@ -8,9 +8,10 @@ import CopyAsMarkdown from '@components/CopyAsMarkdown';
 import Badge from '@components/Badge.astro';
 import { buildUrl } from '@utils/url-builder';
 import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
-import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isResourceDocsEnabled } from '@utils/feature';
 import { getIcon } from '@utils/badges';
 import { collectionToResourceMap } from '@utils/collections/util';
+import { getResourceDocTypeLabel } from '@utils/collections/resource-docs';
 
 import { Page } from './_index.data';
 
@@ -36,6 +37,7 @@ const docsBasePath = `/docs/${props.data.resourceCollection}/${props.data.resour
 const singularResourceName =
   collectionToResourceMap[props.data.resourceCollection as keyof typeof collectionToResourceMap] ??
   props.data.resourceCollection.slice(0, props.data.resourceCollection.length - 1);
+const typeLabel = getResourceDocTypeLabel(props.data.type);
 const chatEnabled = isEventCatalogChatEnabled();
 const chatQuery = `Tell me about the ${props.data.type} doc "${title}" for ${props.data.resourceId} (version ${props.data.version})`;
 
@@ -51,20 +53,22 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro) so docs feel like part of the resource. */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
           <div class="flex flex-col gap-4">
-            <div class="flex items-center gap-4">
-              <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
-            </div>
-            {props.data.summary && <p class="text-base text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
-            {
-              badges.length > 0 && (
-                <div class="flex flex-wrap gap-1.5 py-1">
-                  {badges.map((badge: any) => <Badge badge={badge} />)}
-                </div>
-              )
-            }
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{typeLabel}</span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+          </div>
+          {props.data.summary && <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
+          {
+            badges.length > 0 && (
+              <div class="flex flex-wrap gap-1.5 pt-4">
+                {badges.map((badge: any) => <Badge badge={badge} />)}
+              </div>
+            )
+          }
+          <div class="pt-5">
             <CopyAsMarkdown
               client:only="react"
               variant="toolbar"
@@ -72,9 +76,9 @@ const pagefindAttributes =
               chatQuery={chatQuery}
               chatEnabled={chatEnabled}
               editUrl=""
-              markdownDownloadEnabled={true}
+              markdownDownloadEnabled={isMarkdownDownloadEnabled()}
               rssFeedEnabled={false}
-              preferChatAsDefault={false}
+              preferChatAsDefault={chatEnabled}
             />
           </div>
         </div>
@@ -92,7 +96,7 @@ const pagefindAttributes =
             )
           }
         </div>
-        <div class="prose py-4 max-w-none">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
       </div>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro

@@ -66,7 +66,7 @@ const pagefindAttributes =
 <VerticalSideBarLayout title={pageTitle} description={`GraphQL schema for ${data.name}`}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
         <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
           <div>
             <div class="flex justify-between items-start">

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

@@ -10,6 +10,8 @@ import Footer from '@layouts/Footer.astro';
 
 import components from '@components/MDX/components';
 import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import ArchitectureGraph from '@components/MDX/ArchitectureGraph/ArchitectureGraph.astro';
+import { architectureGraphPortalId } from '@components/MDX/ArchitectureGraph/ArchitectureGraphPortal';
 import SchemaViewer from '@components/MDX/SchemaViewer/SchemaViewerRoot.astro';
 import Admonition from '@components/MDX/Admonition';
 import VersionList from '@components/Lists/VersionList.astro';
@@ -65,6 +67,7 @@ import {
   isVisualiserEnabled,
   isRSSEnabled,
   isEventCatalogMCPEnabled,
+  isArchitectureGraphEnabled,
 } from '@utils/feature';
 import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
 
@@ -361,6 +364,20 @@ const contextDiagrams = contextDiagramSupported
     })
   : [];
 
+// Architecture graphs embedded via <ArchitectureGraph />. Renders the D3
+// catalog-wide force graph focused on the current resource's neighbourhood;
+// `id` + `type` focus another resource instead. Each renders into its own
+// portal, so it never collides with the page's NodeGraph.
+const architectureGraphs = (getMDXComponentsByName(props.body || '', 'ArchitectureGraph') || []).map((graph: any) => ({
+  id: graph.id ?? props.data.id,
+  collection: graph.type ? resourceToCollectionMap[graph.type as keyof typeof resourceToCollectionMap] : props.collection,
+  depth: graph.depth ? Number(graph.depth) : undefined,
+  lens: graph.lens,
+  search: parseMdxBooleanProp(graph.search, true),
+  legend: parseMdxBooleanProp(graph.legend, true),
+  lensPicker: parseMdxBooleanProp(graph.lensPicker, false),
+}));
+
 // Get props for the node graph (when no id is passed, we assume its the current page)
 const hasCurrentFlowEmbed =
   props.collection === 'flows' &&
@@ -408,8 +425,8 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
 <VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-6 pt-4">
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
           <div>
             <div>
               <div class="flex flex-col gap-4">
@@ -447,7 +464,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
               </div>
             </div>
 
-            <h2 class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
+            <p class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
             {
               badges && (
                 <div class="flex flex-wrap gap-1.5 pt-4">
@@ -596,7 +613,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
           }
         </div>
 
-        <div class="prose prose-md py-4 w-full text-[15px]">
+        <div class="prose prose-md pt-8 pb-4 w-full text-[15px]">
           <Content components={components(props)} />
         </div>
         <div data-pagefind-ignore>
@@ -653,6 +670,30 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
                 />
               ))
           }
+          {
+            architectureGraphs.length > 0 &&
+              architectureGraphs.map((graph: any, occurrenceIndex: number) => (
+                <ArchitectureGraph
+                  id={graph.id}
+                  collection={graph.collection}
+                  depth={graph.depth}
+                  lens={graph.lens}
+                  showSearch={graph.search}
+                  showLegend={graph.legend}
+                  showLensPicker={graph.lensPicker}
+                  portalId={architectureGraphPortalId(graph.id, occurrenceIndex)}
+                  href={
+                    isArchitectureGraphEnabled()
+                      ? {
+                          label: 'Open full screen',
+                          // Base URL only — the graph appends its live view state (focus, depth, lens)
+                          url: buildUrl('/visualiser/graph'),
+                        }
+                      : undefined
+                  }
+                />
+              ))
+          }
         </div>
         <Footer />
         <!-- Add edit this page button  with icon and text-->

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

@@ -29,6 +29,8 @@ const hrefForResource = (collection: SystemResourceCollection, id: string, versi
   return buildUrl(`/docs/${collection}/${id}/${version}`);
 };
 
+const ownerTypeLabel = ownerCollection === 'domains' ? 'Domain' : 'System';
+
 const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, items }) =>
   items.map((item: any) => ({
     collection,
@@ -45,16 +47,22 @@ const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, it
 <VerticalSideBarLayout title={`${data.name} | Resources`}>
   <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
     <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
-        <div class="border-b border-[rgb(var(--ec-page-border))] pb-4">
-          <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name} Resources</h2>
-          <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">
-            A group of resources that are mapped to the {data.name}{' '}
-            {ownerCollection === 'domains' ? 'domain' : 'system'}.
-          </h2>
+      <div class="w-full min-w-0 lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {/* Header mirrors the resource page (docs/[type]/[id]/[version]/index.astro). */}
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-3 pt-4">
+          <div class="flex flex-col gap-4">
+            <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{ownerTypeLabel}</span>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+              {data.name} Resources
+            </h2>
+          </div>
+          <p class="text-base pt-4 pb-1 text-[rgb(var(--ec-page-text-muted))] font-light">
+            {resources.length} {resources.length === 1 ? 'resource' : 'resources'} mapped to the {data.name}{' '}
+            {ownerTypeLabel.toLowerCase()}.
+          </p>
         </div>
 
-        <div class="py-8 w-full">
+        <div class="pt-8 pb-4 w-full">
           <SystemResourcesTable resources={resources} client:only="react" />
         </div>
       </div>