@eventcatalog/core 4.1.2 → 4.1.4

package/dist/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md

@@ -0,0 +1,170 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Patterns for shared messages
+title: Patterns for shared messages
+description: Understand the patterns for shared messages in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+You can store your events, commands and queries in any folder in your EventCatalog.
+
+Here are some common usecases:
+
+- [Messages defined by the service](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#messages-defined-by-the-service)
+- [Messages defined at a domain level](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#define-messages-at-a-domain-level)
+- [Messages defined at a system level](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#define-messages-at-a-system-level)
+
+### Messages defined by the service
+
+If you want to keep your message definition close to the service that producers or consumes it you can store them in the `/services` folder.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the `/services/Orders` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'commands',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'AddOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'queries',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'GetOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Define messages at a domain level
+
+If you want to share messages across multiple services you can define them in the `/domains` folder.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the `/domains/Orders` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Define messages at a system level
+
+If you want to share messages across all your domains you can define them in the root of your catalog.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the root of your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderPlaced',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'AddOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'GetOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>

package/dist/docs/development/guides/{messages/common/09-grouping-messages.md → resources/messages/04-connect-messages/03-group-messages.md}

@@ -3,16 +3,14 @@ keywords:
 - EventCatalog messages
 - message groups
 - visualiser
-sidebar_label: Grouping messages
-title: Grouping messages
+sidebar_label: Group messages
+title: Group messages
 description: Learn how to group related messages in the visualiser to reduce clutter.
 sidebar_position: 4
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="3.27.0" />
-
 When a service sends or receives many messages, the visualiser can become crowded. You can use the `group` field on any `sends` or `receives` entry to collect related messages into a named **group node**.
 
 ## Adding groups to messages

package/dist/docs/development/guides/resources/messages/04-connect-messages/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Connect messages",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/connect-messages",
+    "description": "Connect messages to producers, consumers, services, domains, and systems."
+  }
+}

package/dist/docs/development/guides/{channels → resources/messages/04-message-channels}/01-introduction.md

@@ -10,12 +10,10 @@ description: What are channels? Why are they useful for event-driven architectur
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="2.13.0" />
-
-In EventCatalog a channel represents the organization and transmission of messages. 
-
 Channels in EventCatalog describe how a messages transport between producers and consumers. You can use the channels resource to help your team understand how your messages are transported.
 
+Example of channels (not limited to) can be topics, queues, buses.
+
 ```mermaid 
 sequenceDiagram
     participant P as Producer
@@ -28,19 +26,7 @@ sequenceDiagram
 ```
 <br/>
 
-Channels are resources in EventCatalog that you can define in a `/channels` directory. 
-The channel directory can be defined anywhere in your EventCatalog or you can have many channel directories in your EventCatalog.
-
-<!-- Any message ([event](/docs/development/guides/messages/events/introduction), [command](/docs/development/guides/messages/commands/introduction) or [query](/docs/development/guides/messages/queries/introduction)) can be associated to one or many channels. -->
-
-### Example of a channels are visualized in EventCatalog
-
-Here is an example of the `Orders Service` publishing an event `Order amended` over a `Kafka` channel.
-
-![Example](../img/channels/channels-example.png)
-<!-- <a class="block" href="https://demo.eventcatalog.dev/visualiser/services/InventoryService/0.0.2">View demo</a> -->
-
-### Routing messages through multiple channels
+<!-- ### Routing messages through multiple channels
 
 <AddedIn version="2.55.0" />
 
@@ -59,24 +45,17 @@ Or if you are using an Event Bus this channel could be your bus, queue or topic.
 You can model as many channels as you like, and you can route messages through multiple channels.
 :::
 
-![Example](../img/channels/channel-chains.png)
+![Example](../../../img/channels/channel-chains.png) -->
 
 
 ### Supported Channel Protocols
 
-**EventCatalog is technology agnostic**, so can work with any protocol.
-
-Using channels you can define the `protocol` used, this can be one or many protocols.
-
 Here is a list of protocols that are supported by EventCatalog (with icons)
 
 - [amqp](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol#:~:text=The%20Advanced%20Message%20Queuing%20Protocol,protocol%20for%20message%2Doriented%20middleware.)
 - [azure-event-hubs](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-about)
-    - _Added in EventCatalog 2.37.4_
 - [azure-service-bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
-    - _Added in EventCatalog 2.37.4_
 - [azure-eventgrid](https://learn.microsoft.com/en-us/azure/event-grid/overview)
-    - _Added in EventCatalog 2.37.4_
 - [eventbridge](https://aws.amazon.com/eventbridge/)
 - [googlepubsub](https://cloud.google.com/pubsub)
 - [grpc](https://grpc.io/)
@@ -93,12 +72,9 @@ Here is a list of protocols that are supported by EventCatalog (with icons)
 - [solace](https://solace.com/products/apis-protocols/)
 - [sqs](https://aws.amazon.com/sqs/)
 - [tibco-ftl](https://www.tibco.com/products/tibco-ftl)
-    - _Added in EventCatalog 2.37.4_
 - [tibco-rv](https://docs.tibco.com/products/tibco-rendezvous)
-    - _Added in EventCatalog 2.37.4_
 - [ws](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
 - [webrtc](https://webrtc.org/)
-    - _Added in EventCatalog 2.55.1_
 - [zmq](https://zeromq.org/)
 
 If you are using a protocol that is not on this list, please raise on issue on [GitHub](https://github.com/event-catalog/eventcatalog) so we can get the icon supported.

package/dist/docs/development/guides/{channels → resources/messages/04-message-channels}/02-adding-channels.md

@@ -8,34 +8,81 @@ description: Creating and managing channels within EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="2.13.0" />
+A message channel documents how messages are transported between producers and consumers. A channel might represent a Kafka topic, queue, event bus, HTTP route, webhook, or any other transport your architecture uses.
 
-Adding a channel to your Catalog is a great way for you to document how messages are transported between producers and consumers.
-
-### What do channels look like in EventCatalog?
-
-![Example](../img/channels/channel-page-example.png)
-<a href="https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0" class="block">View demo</a>
+![Example](../../../img/channels/channel-page-example.png)
 
 ## Adding a new channel
 
-To add a new channel create a new folder called `channels` and then add your channel files to it.
-
-- `**/channels/{Channel Name}/index.mdx` 
-  - (example `**/channels/EventsChannel/index.mdx`)
-  - (example `**/channels/inventory.{env}.events/index.mdx`)
-  - (example `**/channels/EventBus/index.mdx`)
-
-Channels can be defined in any folder you like. This let's you group channels by domains, service, teams anything you want.
-
-### Creating the channel file
-
-Within your channel folder you will need to create an `index.mdx` file.
-
-The `index.mdx` contents are split into two sections, **frontmatter** and the **markdown content**.
-
-_Here is an example of what a channel markdown file may look like. [You can read the API docs for the channel front matter API](/docs/api/channel-api)_
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog channel">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/message-channels/adding-channels.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/channels.md then help me create a new EventCatalog channel in my catalog.
+
+Ask me for the channel name, address, protocol, summary, whether the channel belongs at the root of the catalog or inside a service, domain, or system, and any known messages routed through it. Then create the correct channels/{'{Channel Name}'}/index.mdx, services/{'{Service Name}'}/channels/{'{Channel Name}'}/index.mdx, domains/{'{Domain Name}'}/channels/{'{Channel Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/channels/{'{Channel Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the channel address has dynamic parts, ask me for the parameters and document them in the channel frontmatter.
+
+If the catalog does not have any services, domains, or systems, put it into the root channels folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the channel should live, create the right folder structure, and add the first version of the channel documentation.
+
+### Manual Creation
+
+Channels live in a `/channels` folder. This folder can be placed anywhere in your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'channels',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'inventory.{env}.events',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'channels',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'orders.events',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+_Here is an example of what a channel markdown file may look like. [You can read the channel reference](/docs/development/guides/resources/messages/message-channels/reference)._
 
 ```md title="/channels/inventory.{env}.events/index.mdx (example)"
 ---
@@ -82,19 +129,9 @@ The Inventory Events channel is the central stream for all inventory-related eve
 
 ```
 
-**That's it!**
-
-Once you add your new channel to EventCatalog, it will now show in the catalog.
-
-With **channels** you can write any Markdown you want and it will render on your page. Every channel gets its own page.
-
-Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.
-
-If you want to see some examples you can [look at the EventCatalog demo on GitHub](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/channels).
-
 ---
 
-## Using parameters in channel names
+### Using parameters in channel names
 
 You may have some channel names/addresses that are dynamic. For example `address: inventory.{env}.events`.
 
@@ -134,9 +171,9 @@ Once this information is defined, it can then be rendered on your page using the
 
 #### Example output using the `<ChannelInformation />` component
 
-![Example](../img/channels/channelinformation-example.png)
+![Example](../../../img/channels/channelinformation-example.png)
 
-## Using protocols in channels
+### Using protocols in channels
 
 Your channel can have one or many protocols. To define a protocol you add the property to your channel.
 
@@ -147,7 +184,7 @@ id: inventory.{env}.events
 # rest of channel markdown...
 
 # You can define one or many protocols
-# list of protocols: https://eventcatalog.dev/docs/development/guides/channels/introduction#protocols
+# list of protocols: https://eventcatalog.dev/docs/development/guides/resources/messages/message-channels/introduction#protocols
 protocols:
   - http
   - kafka
@@ -157,11 +194,9 @@ protocols:
 
 These protocols will be displayed on your channel page and the visualizer.
 
-You can get [the list of protocols here](/docs/development/guides/channels/introduction#protocols).
-
-<AddedIn version="3.18.0" />
+You can get [the list of protocols here](/docs/development/guides/resources/messages/message-channels/introduction#protocols).
 
-## Setting a delivery guarantee
+### Setting a delivery guarantee
 
 You can document the delivery guarantee for your channel using the `deliveryGuarantee` field. This tells consumers what to expect regarding message delivery behavior.
 
@@ -175,24 +210,4 @@ deliveryGuarantee: at-least-once
 ---
 ```
 
-When set, the visualiser shows a colored badge on the channel node. You can read more about the accepted values in the [channel API reference](/docs/api/channel-api#deliveryGuarantee).
-
-## Custom icon
-
-<AddedIn version="3.28.1" />
-
-Set `styles.icon` in your frontmatter to display a custom icon on the channel. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
-
-```md title="/channels/inventory.{env}.events/index.mdx (example)"
----
-id: inventory.{env}.events
-name: Inventory channel
-version: 0.0.1
-styles:
-  icon: /icons/streaming/kafka.svg
----
-```
-
-The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/streaming/kafka.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/apachekafka`).
-
-
+When set, the visualiser shows a colored badge on the channel node. You can read more about the accepted values in the [channel reference](/docs/development/guides/resources/messages/message-channels/reference#deliveryGuarantee).

package/dist/docs/development/guides/{channels → resources/messages/04-message-channels}/04-adding-messages-to-services.md

@@ -9,19 +9,15 @@ description: Understanding how to route messages through channels
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="2.65.0" />
+When you define a message (command, query or event) in EventCatalog, you can also specify how this message is transported (channel).
 
-Services in EventCatalog can **send** and **receive** messages.
-
-When you define this you can also specify **how** the message is transported using channels.
-
-You do this using the `to` and `from` fields in your service frontmatter.
+You do this using the `to` and `from` fields in your producer/consumer frontmatter.
 
 ### Publishing messages to channels
 
-To publish a message through a channel you need to specify the channel in the `to` field in your service frontmatter.
+To publish a message through a channel you need to specify the channel in the `to` field in your producers frontmatter.
 
-In this example the `OrderService` sends an `OrderPlaced` message to the `orders.events` channel.
+In this example the `OrderService` (service) sends an `OrderPlaced` message to the `orders.events` channel.
 
 ```md title="/services/Orders/index.mdx (example)"
 ---
@@ -41,9 +37,9 @@ _This assumes you have already defined the `orders.events` channel documentation
 
 ### Consuming messages from channels
 
-To consume a message from a channel you need to specify the channel in the `from` field in your service frontmatter.
+To consume a message from a channel you need to specify the channel in the `from` field in your consumer frontmatter.
 
-In this example the `PaymentService` consumes the `OrderPlaced` message from the `orders.events` channel.
+In this example the `PaymentService` (service) consumes the `OrderPlaced` message from the `orders.events` channel.
 
 ```md title="/services/Orders/index.mdx (example)"
 ---
@@ -62,7 +58,7 @@ receives:
 
 When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
 
-![Example](../img/channels/channels-example.png)
+![Example](../../../img/channels/channels-example.png)
 
 :::tip Turn off channels in the visualizer
 You can turn off the channels in the visualizer by using the visualizer settings in the UI.
@@ -190,7 +186,7 @@ routes:
 
 EventCatalog will understand the channel routes and relationships and create a visual representation of the channels and their relationships.
 
-![Example](../img/channels/channel-chains.png)
+![Example](../../../img/channels/channel-chains.png)
 
 
 ---
@@ -207,7 +203,7 @@ EventCatalog supports different types of messages (commands, events and queries)
 
 Any message can be added to **one or many channels**.
 
-![Example](../img/channels/channels-example.png)
+![Example](../../../img/channels/channels-example.png)
 
 To add messages to a channel you first have to define your messages.
 
@@ -287,6 +283,6 @@ channels:
 
 When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
 
-![Example](../img/channels/visualizer.png)
+![Example](../../../img/channels/visualizer.png)
 
 </details>