@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/messages/common/08-shared-messages-across-boundaries.md

@@ -0,0 +1,70 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Patterns for shared messages
+title: Patterns for shared messages
+description: Understand the patterns for shared messages in EventCatalog.
+---
+
+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/messages/common/shared-messages-across-boundaries#messages-defined-by-the-service)
+- [Messages defined at a domain level](/docs/development/guides/messages/common/shared-messages-across-boundaries#define-messages-at-a-domain-level)
+- [Messages defined at a system level](/docs/development/guides/messages/common/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.
+
+```md
+services/
+  Orders/
+    events/
+      OrderPlaced/
+        index.mdx
+    commands/
+      AddOrder/
+        index.mdx
+    queries/
+      GetOrder/
+        index.mdx
+```
+
+### 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.
+
+```md
+domains/
+  Orders/
+     <!-- The domain documentation -->
+    index.mdx
+    <!-- Here we store our /events, /commands and /queries -->
+    events/
+      OrderPlaced/
+        index.mdx
+```
+
+### 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.
+
+```md
+events/
+  OrderPlaced/
+    index.mdx
+commands/
+  AddOrder/
+    index.mdx
+queries/
+  GetOrder/
+    index.mdx
+```

package/dist/docs/development/guides/messages/common/09-grouping-messages.md

@@ -0,0 +1,98 @@
+---
+keywords:
+- EventCatalog messages
+- message groups
+- visualiser
+sidebar_label: Grouping messages
+title: Grouping 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
+
+Add the `group` field to any message in your service's `sends` or `receives` list. Messages that share the same `group` value are collapsed into a single node.
+
+```md title="/services/WarehouseService/index.mdx"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+  - id: InventoryReserved
+    version: 1.0.0
+receives:
+  - id: PickRequested
+    version: 1.0.0
+    group: Picking
+  - id: PickCancelled
+    version: 1.0.0
+    group: Picking
+  - id: OrderPlaced
+    version: 1.0.0
+---
+```
+
+In this example:
+- `ShipmentDispatched` and `ShipmentFailed` are grouped under **Shipping**
+- `PickRequested` and `PickCancelled` are grouped under **Picking**
+- `InventoryReserved` and `OrderPlaced` remain ungrouped and render as individual nodes
+
+## How groups appear in the visualiser
+
+Grouped messages are displayed as a stacked card node showing the group name and message count.
+
+![Message group expanded in the visualiser](./imgs/message-group-expanded.png)
+
+## Expanding and collapsing groups
+
+Click the group node to expand it. The expanded view shows each individual message inside a container, along with the **full downstream graph** — channels the messages route to and any connected producer or consumer services. This is the same graph that would appear if the messages were ungrouped.
+
+Click **Collapse** to return to the compact group node.
+
+![Message group expanded in the visualiser](./imgs/expanding-groups.png)
+
+## Combining groups with channels
+
+Groups work with channel routing (`to` and `from` fields). When a grouped message defines a channel, the expanded view will show the correct channel path for each message.
+
+```md title="/services/WarehouseService/index.mdx"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+    to:
+      - id: shipping-events-topic
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+receives:
+  - id: PickRequested
+    version: 1.0.0
+    group: Picking
+    from:
+      - id: warehouse-commands-queue
+---
+```
+
+## Tips
+
+- **Group names are per-service** — the same group name on different services creates separate group nodes.
+- **Mix grouped and ungrouped** — not every message needs a group. Ungrouped messages render as individual nodes as usual.
+- **Groups work for events, commands, and queries** — any message type can be grouped.

package/dist/docs/development/guides/messages/common/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Common to all messages",
+  "position": 20,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/common",
+    "description": "A collection of guides to help you understand queries and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/messages/events/01-introduction.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Events
+sidebar_label: What are events?
+title: Understanding events
+description: What are events? Why are they useful for event-driven architectures?
+---
+
+Events are a type of message that represent immutable facts.
+
+In EventCatalog [Services](/docs/development/guides/services/introduction) may send (produce) or receive (consume) events in your architecture.
+
+### Example of an event
+
+An example of an event would be `OrderPlaced` event.
+
+- This event is a fact that an order has been placed.
+- Other services (consumers) may be interested in this event and can typically subscribe to it.
+
+### Events in EventCatalog
+
+- Events in EventCatalog are orange (following [EventStorming conventions](https://www.eventstorming.com/))
+- Events live in the `/events` folder or inside a [service](/docs/development/guides/services/introduction) folder.

package/dist/docs/development/guides/messages/events/02-adding-events.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog events
+sidebar_label: Creating an event
+title: Creating events
+description: Creating and managing events within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Events live in a `/events` folder. This folder can be placed:
+
+- At the root of your catalog, or
+  - `/events/{Event Name}/index.mdx` 
+- Inside a specific service folder.
+  - `/services/{Service Name}/events/{Event Name}/index.mdx` 
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a event markdown file may look like._
+
+```md title="/events/InventoryAdjusted/index.mdx (example)"
+---
+# id of your event, used for slugs and references in EventCatalog.
+id: InventoryAdjusted
+
+# Display name of the event, rendered in EventCatalog
+name: Inventory Adjusted
+
+# Version of the event
+version: 0.0.4
+
+# Short summary of your event
+summary: |
+  Event with the intent to adjust the inventory
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `Inventory Adjusted` event represents intent to adjust the inventory of a given item.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the event will automatically appear across EventCatalog.
+
+## Writing event content
+
+You can write any Markdown inside an event. 
+
+Each event gets its own page, so use this space to fully explain how it works.
+
+You can also use [interactive components](/docs/development/components/using-components) to enrich your documentation.
+
+## Assign producers and consumers to your event
+
+To add producers or consumers to your event you can read the [guide on adding messages to services](/docs/development/guides/messages/common/map-to-producers-and-consumers).
+
+You can also assign your event to one or more [channels](/docs/development/guides/channels/adding-messages-to-services) (e.g Kafka, RabbitMQ, AWS SQS, AWS SNS, etc).
+
+<AddedIn version="3.18.0" />
+
+## Document an HTTP operation
+
+If your event is tied to an HTTP endpoint, you can use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/events/OrderCreated/index.mdx (example)"
+---
+id: OrderCreated
+# ...
+operation:
+  method: POST
+  path: /orders
+  statusCodes:
+    - "201"
+    - "400"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the event node. See the [event API reference](/docs/api/event-api#operation) for all available options.
+
+## Adding schemas to your event
+
+You can add any schema format to your event, you can read the [guide on adding schemas to messages](/docs/development/guides/messages/common/adding-schemas).
+
+## What should I document?
+
+There’s no strict structure, but consider including:
+
+- Purpose – What does this event do and why does it exist?
+- How to trigger it – APIs, SDKs, or UI actions
+- Schema – Payload structure and validation rules
+- Ownership – Who maintains this event?
+- Contributing – How others can propose changes
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the event. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/events/InventoryAdjusted/index.mdx (example)"
+---
+id: InventoryAdjusted
+name: Inventory Adjusted
+version: 0.0.4
+styles:
+  icon: /icons/events/eventbridge.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/events/eventbridge.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/amazoneventbridge`).
+
+## How do events appear in EventCatalog?
+
+![Example](../../img/events/example.png)
+
+

package/dist/docs/development/guides/messages/events/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Events",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/events",
+    "description": "A collection of guides to help you understand events and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/messages/queries/01-introduction.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: What are queries?
+title: Understanding queries
+description: What are queries? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.10.0" />
+
+Queries are a type of message that represent requests for information.
+
+In EventCatalog [Services](/docs/development/guides/services/introduction) may query (send) or accept (receive) queries in your architecture.
+
+### Queries in EventCatalog
+
+- Queries in EventCatalog can be **accepted** by services or **invoked** by services.
+- Queries in EventCatalog are green
+- Queries live in the `/queries` folder.
+
+![Example](../../img/queries/query-example.png)

package/dist/docs/development/guides/messages/queries/02-adding-queries.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog queries
+sidebar_label: Creating a query
+title: Creating queries
+description: Creating and managing queries within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Queries live in a `/queries` folder. This folder can be placed:
+
+- At the root of your catalog, or
+  - `/queries/{Query Name}/index.mdx` 
+- Inside a specific service folder.
+  - `/services/{Service Name}/queries/{Query Name}/index.mdx` 
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a query markdown file may look like._
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+# id of your query, used for slugs and references in EventCatalog.
+id: GetOrder
+
+# Display name of the query, rendered in EventCatalog
+name: Get Order
+
+# Version of the query
+version: 0.0.4
+
+# Short summary of your query
+summary: |
+    Query with the intent to get an order from the system
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `GetOrder` query represents intent to get an order from the system.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the query will automatically appear across EventCatalog.
+
+## Writing query content
+
+You can write any Markdown inside a query. 
+
+Each query gets its own page, so use this space to fully explain how it works.
+
+You can also use [interactive components](/docs/development/components/using-components) to enrich your documentation.
+
+## Assign services to your queries
+
+To add services that invoke or accept your query you can read the [guide on adding messages to services](/docs/development/guides/messages/common/map-to-producers-and-consumers).
+
+You can also assign your query to one or more [channels](/docs/development/guides/channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+<AddedIn version="3.18.0" />
+
+## Document an HTTP operation
+
+If your query maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+id: GetOrder
+# ...
+operation:
+  method: GET
+  path: /orders/{id}
+  statusCodes:
+    - "200"
+    - "404"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the query node. See the [query API reference](/docs/api/query-api#operation) for all available options.
+
+## Adding schemas to your query
+
+You can add any schema format to your query, you can read the [guide on adding schemas to messages](/docs/development/guides/messages/common/adding-schemas).
+
+## What should I document?
+
+There’s no strict structure, but consider including:
+
+- Purpose – What does this query do and why does it exist?
+- How to trigger it – APIs, SDKs, or UI actions
+- Schema – Payload structure and validation rules
+- Ownership – Who maintains this query?
+- Contributing – How others can propose changes
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the query. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+id: GetOrder
+name: Get Order
+version: 0.0.4
+styles:
+  icon: /icons/query/search.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/query/search.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/graphql`).
+
+## How do queries appear in EventCatalog?
+
+![Example](../../img/queries/example.png)
+
+

package/dist/docs/development/guides/messages/queries/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Queries",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/queries",
+    "description": "A collection of guides to help you understand queries and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/owners/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Teams & Users",
+  "position": 11,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/owners",
+    "description": "A collection of guides to help you understand owners and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/owners/teams/01-introduction.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Teams
+sidebar_label: What are teams?
+title: Understanding teams
+description: What are teams in EventCatalog?
+---
+
+In EventCatalog you can assign teams or owners to domains, services or messages.
+
+Teams are collection of users in EventCatalog, and they can have their own documented page.
+
+### Teams in EventCatalog
+
+- Teams live in the `/teams` folder.
+- Teams reference users within it's frontmatter.
+- Teams can own domains, services or messages.
+
+![Example](../../img/teams/example.png)

package/dist/docs/development/guides/owners/teams/02-adding-teams.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog teams
+sidebar_label: Creating a team
+title: Creating teams
+description: Creating and managing teams within EventCatalog.
+---
+
+Adding a team to your Catalog is a great way to add a collection of owners for domain, service or message.
+
+### What do teams look like in EventCatalog?
+
+![Example](../../img/teams/example.png)
+
+## Adding a new team
+
+To add a new team create a new folder within the `/teams` folder with an `md` file.
+
+- `/teams/{team Name}.mdx` 
+  - (example `/teams/full-stack.mdx`)
+
+The `md` contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a team markdown file may look like._
+
+```md title="/teams/full-stack.md (example)"
+---
+# id of the team
+id: full-stack
+
+# display name for the team
+name: Full stackers
+
+# short summary of the team
+summmary: Full stack developers based in London, UK
+
+# members of the team (users live in /users directory)
+members:
+    - dboyne
+    - asmith
+    - msmith
+
+# optional email address to contact the team
+email: test@test.com
+
+# optional slack URL to send them a DM
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+## Overview
+
+The Full Stack Team is responsible for developing and maintaining both the front-end and back-end components of our applications. This team ensures that the user interfaces are intuitive and responsive, and that the server-side logic and database interactions are efficient and secure. The Full Stack Team handles the entire lifecycle of web applications, from initial development to deployment and ongoing maintenance.
+
+```
+
+**That's it!**
+
+Once you add your new team to EventCatalog, it will now show in the docs.
+
+## Adding content
+
+With **teams** you can write any Markdown you want and it will render on your page. Every command gets its own page.
+
+Teams do not support custom components.
+
+### Tips for team content
+
+It's entirely up to you what you want to add to your teams markdown content but here are a few things you might want to consider.
+
+- Context of the team. Who are they? 
+- Contact info for the team?
+

package/dist/docs/development/guides/owners/teams/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Teams",
+  "position": 11,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/teams",
+    "description": "A collection of guides to help you understand teams and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/owners/users/01-introduction.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- users
+sidebar_label: What are users?
+title: Understanding users
+description: What are users in EventCatalog?
+---
+
+In EventCatalog you can assign users or owners to domains, services or messages.
+
+A user represents a person.
+
+### Users in EventCatalog
+
+- Users live in the `/users` folder.
+- Users can own domains, services or messages.
+
+![Example](../../img/users/example.png)