@eventcatalog/core 4.1.2 → 4.1.4

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.1.2";
+var version = "4.1.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-6MLMZ7C6.js";
-import "../chunk-BAPUZSRK.js";
+} from "../chunk-CAYWT7E4.js";
+import "../chunk-TCK7WEEE.js";
 export {
   raiseEvent
 };

package/dist/analytics/count-resources.cjs

@@ -44,14 +44,20 @@ var RESOURCE_PATTERNS = {
   diagrams: ["**/diagrams/**/index.@(md|mdx)"],
   ubiquitousLanguages: ["domains/*/ubiquitous-language.@(md|mdx)", "domains/*/subdomains/*/ubiquitous-language.@(md|mdx)"]
 };
+var CUSTOM_ROUTE_PATTERNS = {
+  customPages: ["pages/**/*.astro"],
+  customApis: ["pages/**/*.@(ts|js|mjs)"]
+};
+var DEFAULT_IGNORES = ["**/versioned/**", "**/dist/**", "**/node_modules/**"];
+var CUSTOM_ROUTE_IGNORES = [...DEFAULT_IGNORES, "pages/**/_*/**", "pages/**/_*"];
 async function countResources(projectDir) {
   const counts = {};
-  for (const [type, patterns] of Object.entries(RESOURCE_PATTERNS)) {
+  for (const [type, patterns] of Object.entries({ ...RESOURCE_PATTERNS, ...CUSTOM_ROUTE_PATTERNS })) {
     let total = 0;
     for (const pattern of patterns) {
       const files = await (0, import_glob.glob)(pattern, {
         cwd: projectDir,
-        ignore: ["**/versioned/**", "**/dist/**", "**/node_modules/**"]
+        ignore: type in CUSTOM_ROUTE_PATTERNS ? CUSTOM_ROUTE_IGNORES : DEFAULT_IGNORES
       });
       total += files.length;
     }

package/dist/analytics/count-resources.js

@@ -1,7 +1,7 @@
 import {
   countResources,
   serializeCounts
-} from "../chunk-DAOXTQVS.js";
+} from "../chunk-K2XIENVT.js";
 export {
   countResources,
   serializeCounts

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.1.2";
+var version = "4.1.4";
 
 // src/constants.ts
 var VERSION = version;
@@ -197,14 +197,20 @@ var RESOURCE_PATTERNS = {
   diagrams: ["**/diagrams/**/index.@(md|mdx)"],
   ubiquitousLanguages: ["domains/*/ubiquitous-language.@(md|mdx)", "domains/*/subdomains/*/ubiquitous-language.@(md|mdx)"]
 };
+var CUSTOM_ROUTE_PATTERNS = {
+  customPages: ["pages/**/*.astro"],
+  customApis: ["pages/**/*.@(ts|js|mjs)"]
+};
+var DEFAULT_IGNORES = ["**/versioned/**", "**/dist/**", "**/node_modules/**"];
+var CUSTOM_ROUTE_IGNORES = [...DEFAULT_IGNORES, "pages/**/_*/**", "pages/**/_*"];
 async function countResources(projectDir) {
   const counts = {};
-  for (const [type, patterns] of Object.entries(RESOURCE_PATTERNS)) {
+  for (const [type, patterns] of Object.entries({ ...RESOURCE_PATTERNS, ...CUSTOM_ROUTE_PATTERNS })) {
     let total = 0;
     for (const pattern of patterns) {
       const files = await (0, import_glob.glob)(pattern, {
         cwd: projectDir,
-        ignore: ["**/versioned/**", "**/dist/**", "**/node_modules/**"]
+        ignore: type in CUSTOM_ROUTE_PATTERNS ? CUSTOM_ROUTE_IGNORES : DEFAULT_IGNORES
       });
       total += files.length;
     }
@@ -263,7 +269,9 @@ var toCloudResourceCounts = (counts) => ({
   users: counts.users || 0,
   designs: counts.designs || 0,
   diagrams: counts.diagrams || 0,
-  ubiquitousLanguages: counts.ubiquitousLanguages || 0
+  ubiquitousLanguages: counts.ubiquitousLanguages || 0,
+  customPages: counts.customPages || 0,
+  customApis: counts.customApis || 0
 });
 var reportCloudResourceInventory = async (configFile, resourceCounts) => {
   const analytics = configFile.cloud?.analytics;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-XDI5KMKL.js";
-import "../chunk-6MLMZ7C6.js";
-import "../chunk-DAOXTQVS.js";
-import "../chunk-BAPUZSRK.js";
+} from "../chunk-RAB6LGHN.js";
+import "../chunk-CAYWT7E4.js";
+import "../chunk-K2XIENVT.js";
+import "../chunk-TCK7WEEE.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-2HP7DWTG.js → chunk-B3HQOT3D.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BAPUZSRK.js";
+} from "./chunk-TCK7WEEE.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-6MLMZ7C6.js → chunk-CAYWT7E4.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BAPUZSRK.js";
+} from "./chunk-TCK7WEEE.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-DAOXTQVS.js → chunk-K2XIENVT.js}

@@ -19,14 +19,20 @@ var RESOURCE_PATTERNS = {
   diagrams: ["**/diagrams/**/index.@(md|mdx)"],
   ubiquitousLanguages: ["domains/*/ubiquitous-language.@(md|mdx)", "domains/*/subdomains/*/ubiquitous-language.@(md|mdx)"]
 };
+var CUSTOM_ROUTE_PATTERNS = {
+  customPages: ["pages/**/*.astro"],
+  customApis: ["pages/**/*.@(ts|js|mjs)"]
+};
+var DEFAULT_IGNORES = ["**/versioned/**", "**/dist/**", "**/node_modules/**"];
+var CUSTOM_ROUTE_IGNORES = [...DEFAULT_IGNORES, "pages/**/_*/**", "pages/**/_*"];
 async function countResources(projectDir) {
   const counts = {};
-  for (const [type, patterns] of Object.entries(RESOURCE_PATTERNS)) {
+  for (const [type, patterns] of Object.entries({ ...RESOURCE_PATTERNS, ...CUSTOM_ROUTE_PATTERNS })) {
     let total = 0;
     for (const pattern of patterns) {
       const files = await glob(pattern, {
         cwd: projectDir,
-        ignore: ["**/versioned/**", "**/dist/**", "**/node_modules/**"]
+        ignore: type in CUSTOM_ROUTE_PATTERNS ? CUSTOM_ROUTE_IGNORES : DEFAULT_IGNORES
       });
       total += files.length;
     }

package/dist/{chunk-XDI5KMKL.js → chunk-RAB6LGHN.js}

@@ -1,10 +1,10 @@
 import {
   raiseEvent
-} from "./chunk-6MLMZ7C6.js";
+} from "./chunk-CAYWT7E4.js";
 import {
   countResources,
   serializeCounts
-} from "./chunk-DAOXTQVS.js";
+} from "./chunk-K2XIENVT.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile
@@ -57,7 +57,9 @@ var toCloudResourceCounts = (counts) => ({
   users: counts.users || 0,
   designs: counts.designs || 0,
   diagrams: counts.diagrams || 0,
-  ubiquitousLanguages: counts.ubiquitousLanguages || 0
+  ubiquitousLanguages: counts.ubiquitousLanguages || 0,
+  customPages: counts.customPages || 0,
+  customApis: counts.customApis || 0
 });
 var reportCloudResourceInventory = async (configFile, resourceCounts) => {
   const analytics = configFile.cloud?.analytics;

package/dist/{chunk-BAPUZSRK.js → chunk-TCK7WEEE.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.1.2";
+var version = "4.1.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-UKC6BKFK.js → chunk-ZLQUICJD.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-2HP7DWTG.js";
+} from "./chunk-B3HQOT3D.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "4.1.2";
+var version = "4.1.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BAPUZSRK.js";
+} from "./chunk-TCK7WEEE.js";
 export {
   VERSION
 };

package/dist/docs/api/02-config.md

@@ -273,7 +273,7 @@ Configure the landing page URL your EventCatalog loads. By default EventCatalog
 
 Clicking on the EventCatalog logo (or [your custom logo](/docs/api/config#logo)), will also go to this URL.
 
-If you set this value the `Home` icon in the vertical navigation will not be shown and your users will be redirected to this default URL.
+If you set this value the `Home` icon in the Application sidebar will not be shown and your users will be redirected to this default URL.
 
 You can set this to any EventCatalog page URL. 
 
@@ -289,26 +289,147 @@ module.exports = {
 };
 ```
 
-### `sidebar` {#sidebar}
+### `navigation` {#navigation}
 
-<AddedIn version="2.30.1" />
+<AddedIn version="4.0" />
 
-- Type: `Array[{ id: string, visible: boolean }]`
+- Type: `object`
+
+Configure navigation in EventCatalog.
 
-Configure the [application sidebar](/docs/development/customization/customize-sidebars/application-sidebar) in EventCatalog.
+Use `navigation.groups` to configure the [Application sidebar](/docs/development/customization/application-sidebar).
 
-Show/hide items in the sidebar, [see list of options](/docs/development/customization/customize-sidebars/application-sidebar#showhide-items-in-the-application-sidebar).
+Use `navigation.pages` to configure the [Documentation sidebar](/docs/development/customization/documentation-sidebar) shown on `/docs/*` pages.
 
 ```js title="eventcatalog.config.js"
 module.exports = {
-  sidebar: {
-    // Will hide the AI chat feature in the sidebar
-    id: '/chat',
-    visible: false
-  }
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'home' }, { id: 'docs' }],
+      },
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          { id: 'schema-insights', visible: false },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [{ id: 'teams' }, { id: 'users' }],
+      },
+      {
+        id: 'settings',
+        position: 'bottom',
+        items: [{ id: 'settings' }],
+      },
+    ],
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+};
+```
+
+#### `navigation.groups`
+
+`navigation.groups` configures the Application sidebar that appears across EventCatalog.
+
+If you do not configure `navigation.groups`, EventCatalog renders the default Application sidebar.
+
+If you do configure `navigation.groups`, your groups replace the default Application sidebar. Add every item you want users to see.
+
+Built-in Application sidebar item IDs include:
+
+- `home`
+- `docs`
+- `catalog`
+- `schemas`
+- `schema-insights`
+- `teams`
+- `users`
+- `settings`
+
+You can also reference built-in route IDs directly, such as `/schemas/explorer`, `/directory/teams`, or `/settings/general`.
+
+Groups support:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique group identifier. |
+| `label` | `string` | Optional label shown above the group. |
+| `visible` | `boolean` | Set to `false` to hide the group. |
+| `position` | `'top' \| 'bottom'` | Use `bottom` for groups pinned below the main navigation. Defaults to `top`. |
+| `items` | `array` | Navigation items in this group. |
+
+Items support:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Built-in item id, route id, or custom item id. |
+| `label` | `string` | Custom label. Required for custom items. |
+| `icon` | `string` | Any icon exported by [lucide-react](https://lucide.dev/icons/), such as `House`, `BookOpen`, or `LifeBuoy`. |
+| `href` | `string` | Required for custom items. Built-in items provide their own `href`. |
+| `visible` | `boolean` | Set to `false` to hide the item. |
+| `match` | `string \| string[]` | Paths that should mark the item as active. Useful for custom navigation items. |
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        label: 'Platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: ['/docs/custom/platform'],
+          },
+          {
+            id: 'support',
+            label: 'Support',
+            icon: 'LifeBuoy',
+            href: 'https://support.example.com',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+External `href` values open in a new tab.
+
+#### `navigation.pages`
+
+`navigation.pages` configures the context-aware Documentation sidebar shown on `/docs/*` pages.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:top-level-domains', 'list:all'],
+  },
 };
 ```
 
+See [Documentation sidebar](/docs/development/customization/documentation-sidebar) for all supported list, resource, group, and custom link options.
+
+:::note Migrating from `sidebar`
+
+In v3 you could show or hide Application sidebar items using the top-level `sidebar` property.
+
+In v4 this has been replaced by `navigation.groups`.
+
+The `SideBarConfig` type is no longer exported.
+
+:::
+
 ### `visualiser` {#visualiser}
 
 <AddedIn version="2.42.0" />
@@ -348,7 +469,11 @@ module.exports = {
 
 - Type: `object`
 
-Configure the [documentation sidebar](/docs/development/customization/customize-sidebars/documentation-sidebar) in EventCatalog.
+Configure documentation rendering options in EventCatalog.
+
+Use `docs.sidebar` for the Documentation sidebar render mode and orphaned message behavior.
+
+Use [`navigation.pages`](#navigationpages) when you want to choose which resources, groups, and custom links appear in the [Documentation sidebar](/docs/development/customization/documentation-sidebar).
 
 ```js title="eventcatalog.config.js"
 module.exports = {
@@ -360,7 +485,7 @@ module.exports = {
 };
 ```
 
-Configuration for the documentation sidebar.
+Configuration for the Documentation sidebar render mode.
 
 ### `docs.sidebar` options
 
@@ -704,7 +829,7 @@ Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly underst
 }
 ```
 
-See the [LLMs documentation](/docs/development/developer-tools/llms.txt) for more information, how you can use it and examples.
+See the [LLMs documentation](/docs/development/ask-your-architecture/llms.txt) for more information, how you can use it and examples.
 
 
 ### `fullCatalogAPIEnabled` {#fullCatalogAPIEnabled}
@@ -749,6 +874,33 @@ module.exports = {
 
 See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
 
+### `systems` {#systems}
+
+<AddedIn version="4.0" />
+
+- Type: `object`
+
+Configuration for the systems table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  systems: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'System' },
+        summary: { visible: true, label: 'Summary' },
+        services: { visible: true, label: 'Services' },
+        flows: { visible: true, label: 'Flows' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
 ### `events` {#events}
 
 <AddedIn version="2.63.0" />

package/dist/docs/api/08-code-blocks.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 100
+sidebar_position: 6
 sidebar_label: Code blocks
 title: Code blocks
 description: Understanding what is possible with EventCatalog code blocks

package/dist/docs/development/00-why-eventcatalog.md

@@ -8,65 +8,54 @@ title: Why EventCatalog?
 description: EventCatalog is an open source project to help you bring discoverability to your event-driven architecture.
 ---
 
-Many companies adopting event-driven architectures end up in a **distributed big ball of mud**.
+Software architecture consists of many different primitives including domains, systems, services, APIS, contracts, messages and many more.
 
-There can be many reasons for this...but one overlooked reason is that teams are not documenting their architectures, they lack standards, governance and discoverability.
+As systems grow, complexity grows. Documentation becomes important for teams but teams struggle to keep docs in sync, or relevant to what they are trying to model.
 
-Your teams start to ask questions like:
+**Many documentation tools are not designed for software architecture**; they let you create generic pages that get lost across the organization, they do not stay in sync with your code, specifications and teams making changes.
 
-- _"What messages do we have?"_
-- _"How are consumers and producers using these messages?"_
-- _"What common fields are across our schemas? What is the drift?"_
-- _"What's the business context behind this architecture?"_
-- _"Where can I find the schemas of these messages?"_
-- _"What services or domains do we have in our architecture?"_
-- _"How can I make changes?"_
-- _"Who is consuming these messages?"_
-- _And the list goes on..._
+**Our vision with EventCatalog is to change this.**
 
-Time is lost hunting through multiple tools to find the answers to these questions.
+### What is EventCatalog?
 
-**What if you could answer these questions in minutes?**
+EventCatalog is a documentation and governance tool that is built for architects.
 
-EventCatalog is designed to help you avoid the chaos, by providing a way to document your architecture, visualize it, and provide tools to help your teams and AI tools to save time and get answers to the questions when they need them.
+ It lets you document and visualize your architecture with primitives you are already familiar with. You can document domains, systems, applications and schemas and visualize how they all relate to each other.
 
----
-
-## What is EventCatalog?
+EventCatalog creates an internal architecture graph of how your systems work. This makes EventCatalog accessible to your AI agents, LLMs and AI workflows and [creates context of your business and architecture](/docs/development/ask-your-architecture/intro).
 
-[EventCatalog is a self-hosted open source project](https://github.com/event-catalog/eventcatalog) to help you bring discoverability to your architecture through documentation, visualization, and design for both humans and AI.
+EventCatalog is technology agnostic, this means you can document and model any systems you have
 
-EventCatalog models your architecture as structured, versioned knowledge — not just pages of documentation — so it can be searched, visualized, and queried reliably over time.
-
-**EventCatalog is technology agnostic**, you can use it and integrate with any broker, schema format, or stack.
 
 #### What can EventCatalog do for you?
 
-- **Save time and help your teams find answers fast**
-  - Search your entire architecture — domains, services, events, data products, schemas, owners — in seconds
-  - Stop asking "who owns this?" or "what consumes this event?"
-- **Keep documentation and specifications in sync**
-  - Auto-generate docs from your OpenAPI, AsyncAPI, or schema registries
-  - Documentation that updates when your specs update
-  - Write custom integrations with the [EventCatalog SDK](/docs/sdk)
-- **Query your architecture with AI**
+- **Save time across the organization**
+  - Help teams find information they need across your business and organization
+  - Document high level information for stakeholders while providing lower level details to your teams.
+  - Connect to your AI Agents and AI Workflows. Give your LLMs the context they need.
+- **Create documentation you can trust**
+  - Sync documentation from your code with our Agent
+  - Automate documentation from your OpenAPI, AsyncAPI, or schema registries
+  - Use EventCatalog Agent to sync code to docs from your CI/CD workflows.
+  - Write your own automation and plugins with the [EventCatalog SDK](/docs/sdk)
+- **Detect breaking changes before they reach production**
+  - Use EventCatalog Agent to detect breaking schema changes
+  - Bring your own model and get notified when things break
+- **Use natural langugage to query your architecture**
   - Connect AI tools to your architecture using [EventCatalog's MCP server](/docs/development/ask-your-architecture/mcp-server/introduction)
   - Ask architectural questions grounded in your documented domains, services, events, data products, and schemas
-- **See the bigger picture**
-  - Visualize your architecture, domains, services, and message flows
-  - Document business workflows and draft new ideas
-  - Understand how everything connects — without digging through code
-- **Design what's next**
-  - Capture business workflows and plan changes visually
-  - Use your real architecture as building blocks
+- **Show the bigger picture**
+  - Help business stakeholders understand the bigger picture
+  - Visualize your architecture and future ideas
+  - Document key business workflows
 
 **EventCatalog is self-hosted. You own your data and host it wherever you want.**
 
 ---
 
-## Why we built this
+<!-- ## Why we built this
 
-Event-driven architectures start simple but grow complex fast. More services, more events, more teams — and suddenly nobody knows how anything connects.
+Distributed architecture starts simple but grow complex fast. More services, more events, more teams — and suddenly nobody knows how anything connects.
 
 EventCatalog brings discoverability, documentation, and visualization to your architecture — so teams can reason about change before it happens, not after.
 
@@ -75,7 +64,7 @@ EventCatalog brings discoverability, documentation, and visualization to your ar
 <iframe width="100%" height="415" src="https://www.youtube.com/embed/VLUvfIm9wnQ?si=XEEkOqHyZBynqZHo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 </details>
 
----
+--- -->
 
 ## Join the community
 

package/dist/docs/development/01-fundamentals.md

@@ -8,18 +8,66 @@ title: Fundamentals
 description: Understanding the fundamentals of EventCatalog
 ---
 
-EventCatalog allows you to document your [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/services/introduction), [messages](/docs/development/guides/messages/overview) ([events](/docs/development/guides/messages/events/introduction), [commands](/docs/development/guides/messages/commands/introduction), [queries](/docs/development/guides/messages/queries/introduction)), [data products](/docs/development/guides/data-products/introduction), [data stores](/docs/development/guides/data/introduction), [diagrams](/docs/development/guides/diagrams/introduction), [schemas](/docs/development/guides/schemas/introduction), [specifications](/docs/development/guides/services/adding-to-services/openapi) and more.
+EventCatalog is a architecture catalog built around software primitives and domain-driven design patterns, so you can model the systems you actually build instead of creating disconnected documentation pages.
 
-You can manually document these resources or you can automate the documentation process using EventCatalog integrations (e.g. [OpenAPI](/integrations/openapi), [AsyncAPI](/integrations/asyncapi), [GraphQL](/integrations/graphql) or schema registries), it's up to you.
+EventCatalog gives your teams and AI agents a shared understanding of how your systems work across your organization.
 
-EventCatalog is flexible and can fit any workflow you have. Deploy it once a day, or 100 times a day. Connect it to external systems like schema registries, API management platforms, or your own custom integrations.
+EventCatalog is an open source project and is self-hosted and follows the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) pattern. All pages in EventCatalog are powered by [markdown (MDX)](https://mdxjs.com/).
 
-EventCatalog is powered by [markdown files (MDX)](https://mdxjs.com/) and can be used in any markdown editor or IDE.
+Your catalog is private, stays in your own repository and infrastructure. 
 
-### Docs-as-code
+At its core, EventCatalog gives you a small set of building blocks.
+
+- **Domains (Level 1)** - a domain describes a business boundary
+- **Systems (Level 2)** - a system is a collection of resources that work together to perform a function.
+- **Resources (Level 3)** - individual resources (e.g services, messages, data stores) that can be assigned to systems or domains.
+
+All building blocks are optional, it's up to you how you want to model your architecture in your catalog.
+
+![EventCatalog model showing domains, systems, resources, contracts, and ownership](./img/ec-types.png)
+
+## The EventCatalog model
+
+Domains give your catalog a business shape. They help users understand the boundaries in your architecture, such as `Shopping`, `Payments`, `Fulfilment`, or `Customer`.
+
+Systems give your catalog an operating shape. A system is a collection of resources that work together to perform a function. For example, a `Shopping` domain might contain a `Cart System` and a `Promotion System`.
+
+Resources are the documented building blocks inside your architecture. They can include:
+
+- [Services](/docs/development/guides/resources/services/introduction), such as APIs, workers, frontends, and backends.
+- [Messages](/docs/development/guides/resources/messages/what-are-messages), such as events, commands, and queries.
+- [Data stores](/docs/development/guides/resources/data/introduction), such as databases, caches, and file stores.
+- [Entities](/docs/development/guides/resources/entities/introduction), such as `Order`, `Customer`, or `Payment`.
+- [Data products](/docs/development/guides/resources/data-products/introduction), such as warehouse tables or analytical datasets.
+- [Agents](/docs/development/guides/resources/agents/introduction), such as customer support AI agents.
+- [Flows](/docs/development/guides/resources/flows/introduction), such as business workflows.
+
+Contracts are attached to resources. Schemas, OpenAPI specs, AsyncAPI specs, and GraphQL schemas help users understand the data and interfaces that resources produce, consume, or implement.
+
+Teams and users can own domains, systems, resources, and contracts. This makes ownership part of the architecture model, not a separate spreadsheet.
+
+## Levels of detail
+
+EventCatalog is useful to anyone in your organization. You can define high level primitives whilst giving lower level implementation details.
+
+| Level | Name | What it answers | Example |
+|-------|------|-----------------|---------|
+| Level 1 | Domains | High level, what business boundary are we looking at? | Shopping |
+| Level 2 | Systems | What software capability exists inside that boundary? | Cart System |
+| Level 3 | Resources | What makes up, connects to, or documents that system? | Cart API, cart database, checkout flow |
+
+Contracts and ownership sit across these levels. A service can implement an OpenAPI contract. A message can have a schema. A team can own a domain, system, or resource.
+
+This gives different users a way into the same catalog. Architects can start at domains, platform teams can reason about systems, and developers can drill into the resources and contracts they work with every day.
+
+## Docs-as-code
 
 EventCatalog is a [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) tool. This means you can store your documentation in your existing Git repository, version it, and use your existing workflows to review and merge changes.
 
+This also let's you define custom workflows and patterns in your organization for documentation and automation. 
+
+It's up to you where you define your catalog (or catalogs). Here are some examples:
+
 | Pattern | Description |
 |---------|-------------|
 | **Standalone repo** | Keep documentation separate from code |
@@ -27,9 +75,12 @@ EventCatalog is a [docs-as-code](https://www.writethedocs.org/guide/docs-as-code
 | **Monorepo** | Documentation as part of your existing monorepo |
 | **Federated** | Multiple EventCatalog instances connected into one view |
 
-EventCatalog does not force you to use a specific broker, schema format, or stack. You can use it with any broker, schema format, or stack and can fit into any workflow you have. EventCatalog fits your workflow, not the other way around.
 
-### Visual editing
+## Automation
+
+Your documentation can also be automated, keeping your implementation details close to your documentation. There are many [integrations](/integrations) or you can create your own automations with our [SDK](/docs/sdk).
+
+## Visual editing
 
 You can also use [EventCatalog Editor](/docs/editor/overview) to maintain your catalog through a local visual workflow.