@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/resources/services/02-create-service.md

@@ -0,0 +1,195 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Create a service
+title: Create a service
+description: Creating and managing services 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';
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+![Example](../../img/services/service-example.png)
+
+## Adding a new service
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog service">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/services/create-service.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/services.md then help me create a new EventCatalog service in my catalog.
+
+Ask me for the service name, what it does, summary, whether it belongs inside a domain or system, and any known messages, or specifications. Then create the correct services/{'{Service Name}'}/index.mdx, domains/{'{Domain Name}'}/services/{'{Service Name}'}/index.mdx, systems/{'{System Name}'}/services/{'{Service Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service 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 catalog does not have any domains, or systems, just assume and put it into the root of the catalog, no need to ask about systems or domains.
+
+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 service should live, create the right folder structure, and add the first version of the service documentation.
+
+### Manual Creation
+
+Services can live at the root of your catalog, inside a domain, inside a system, or inside a system that belongs to a domain.
+
+Create a new folder for the service with an `index.mdx` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the service belongs to a domain, keep it inside that domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'services',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrdersService',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Services can also live inside systems:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'CartAPI',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+_Here is an example of what a service markdown file may look like._
+
+```md title="/services/Orders/index.mdx (example)"
+---
+# id of your service, used for slugs and references in EventCatalog.
+id: Orders
+
+# Display name of the Service, rendered in EventCatalog
+name: Orders
+
+# Version of the Service
+version: 0.0.1
+
+# Short summary of your Service
+summary: |
+  Service that contains order related information
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional messages this service receives and it's version
+receives:
+  - id: InventoryAdjusted
+    version: 0.0.3
+
+# Optional messages this service sends and it's version
+sends:
+  - id: AddInventory
+    version: 0.0.3
+
+# Optional flows associated with this service
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+This orders service gives API consumers the ability to produce orders in the systems. Events are raised from this system for downstream consumption.
+
+<NodeGraph />
+
+```
+
+## Adding content
+
+With **services** you can write any Markdown you want and it will render on your page. Every service gets its own page.
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.

package/dist/docs/development/guides/resources/services/03-create-external-service.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog services
+- External services
+sidebar_label: Create an external service
+title: Create an external service
+description: Model third-party services like Stripe, Twilio, or Snowflake as external services in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.28.0" />
+
+External services are services your architecture integrates with but does not own — Stripe, Twilio, Snowflake, Auth0, and similar third-party providers. They behave like any other service in EventCatalog: they can send and receive messages, be versioned, have owners, and carry specifications. The only difference is how they are presented — purple with a Globe icon and an "External System" badge in the visualiser, and grouped under a dedicated "External Services" section in the sidebar (or "External Integrations" when inside a domain).
+
+Creating an external service is identical to creating a regular service — just add `externalSystem: true` to the frontmatter.
+
+## Example: modelling Stripe
+
+Here is an example modelling Stripe as an external service. Stripe receives a `ChargeCard` command from your `PaymentGatewayService` and sends back `StripeChargeSucceeded` and `StripeChargeFailed` webhook events.
+
+```md title="/services/Stripe/index.mdx (example)"
+---
+id: Stripe
+name: Stripe
+version: 1.0.0
+summary: External payment processor used to charge customer cards.
+externalSystem: true
+receives:
+  - id: ChargeCard
+    version: 0.0.1
+sends:
+  - id: StripeChargeSucceeded
+    version: 0.0.1
+  - id: StripeChargeFailed
+    version: 0.0.1
+---
+
+## Overview
+
+Stripe is used to process card payments. We send a `ChargeCard` command and Stripe
+webhooks back `StripeChargeSucceeded` or `StripeChargeFailed` to complete the round trip.
+
+<NodeGraph />
+```
+
+Your paired `PaymentGatewayService` would mirror this — `sends: [ChargeCard]` and `receives: [StripeChargeSucceeded, StripeChargeFailed]` — giving you a complete integration contract visible in the visualiser.
+
+![Stripe rendered as an external service in the EventCatalog visualiser](./img/services/external-system-stripe.png)
+
+Modelling third-party systems this way lets you document exactly what you call and what they call back, see external dependencies cleanly separated from your own services on the visualiser, and reason about which of your services depend on which third parties.

package/dist/docs/development/guides/resources/services/04-add-resources-to-services/01-add-messages-to-services.md

@@ -0,0 +1,142 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 1
+sidebar_label: Add messages to services
+title: Add messages to services
+description: Understanding how to add messages to services.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A service in EventCatalog can **receive** (consume) or **send** (produce) messages ([commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) and [queries](/docs/development/guides/resources/messages/message-types/queries)). 
+
+![Example](../../../img/services/example.png)
+
+## Producing and consuming messages from your service
+
+To add messages to your service you first have to define your messages, if you don't have any messages you can create one.
+
+To add messages to a service you need to define them in either the **sends** or **receives** array within your service frontmatter API.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # id of the message this service receives (consumes)
+    - id: PaymentProcessed
+    # (optional) The version of the message you want to add.
+    # Supports semver matching (e.g ^1.0.1, 1.x.x). 
+    # But if no version is given the latest version of the message will be used.
+      version: 0.0.1
+sends:
+    # id of the message this service sends (produces)
+    - id: OrderProcessed
+      version: 2.x.x
+---
+
+<!-- Markdown contents... -->
+
+```
+
+:::info The power of versioning
+  When you define your messages for your service you can define the version of them too. This can be powerful if you have multiple versions of your events, commands or queries. Example could be an API that you are consuming, maybe you are consuming an old version of this API you can specify that.
+:::
+
+### Routing messages through channels
+
+Messages may also travel through [channels](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) (e.g message brokers, queues, buses).
+
+To specify a channel you need to use the `to` and `from` fields in your service frontmatter.
+
+This example shows :
+- the `OrderService` sending an `OrderPlaced` message to the `orders.events` channel.
+- the `OrderService` consuming the a `PaymentProcessed` message from the `payments.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+
+# Service sends a message called OrderPlaced
+# This message is published to the orders.events channel (e.g broker)
+sends:
+  - id: OrderPlaced
+    to:
+      # The id of the channel (e.g queue)
+      - id: orders.events
+
+# Service consumes a message called PaymentProcessed
+# This message is consumed from the payments.events channel (e.g queue)
+receives:
+  - id: PaymentProcessed
+    from:
+      # The id of the channel (e.g bus)
+      - id: payments.events
+---
+```
+
+You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/resources/messages/message-channels/introduction).
+
+
+<!-- ### Group messages in the visualiser
+
+<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.
+
+```md title="/services/WarehouseService/index.mdx (example)"
+---
+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: PickRequested
+    version: 1.0.0
+    group: Picking
+receives:
+  - id: OrderPlaced
+    version: 1.0.0
+    group: Orders
+---
+```
+
+Messages that share the same `group` value are collapsed into a single stacked (purple) card node in the visualiser. The node displays the group name and the number of messages it contains.
+
+![Message group expanded in the visualiser](../../../img/services/message-group-expanded.png)
+
+Click the group node to expand it. The expanded view renders each individual message inside a container, along with the full downstream graph: channels the messages route to and any connected producer or consumer services, exactly as they would appear when ungrouped. Click **Collapse** inside the expanded container to return to the compact group node.
+
+![Message group expanded in the visualiser](../../../img/services/expanding-groups.png)
+
+Groups can be combined with channel routing. The expanded view will show the correct channel paths for each message.
+
+```md title="/services/WarehouseService/index.mdx (example)"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+    to:
+      - id: shipping.events
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+---
+``` -->
+
+<!-- ### Visualizing messages within a service
+
+When messages get added within your services EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.
+
+![Example](../../../img/services/visualiser.png) -->

package/dist/docs/development/guides/resources/services/04-add-resources-to-services/02-add-data-stores-to-services.md

@@ -0,0 +1,45 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 2
+sidebar_label: Add data stores to services
+title: Add data stores to services
+description: Adding data stores to services
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+In EventCatalog a [data store](/docs/development/guides/resources/data/introduction) is a persistent storage system (e.g database, cache, index) that holds information used by one or resources.
+
+Your service can **read** and/or **write** to any data store documented in your catalog.
+
+## Specifying read/write relationships
+
+To document the read/write relationship from a service to a data store you use the **writesTo** or **readsFrom** array within your service frontmatter API.
+
+In the example below the `OrderService` writes to the `OrdersDatabase` and reads from the `ProductRedisCache`.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+writesTo:
+    # id of the data store this service writes to
+    - id: OrdersDatabase
+readsFrom:
+    # id of the data store this service reads from
+    - id: ProductRedisCache
+      # optional version of the data store if none provided latest will be used
+      # also supports sever matching (0.x.x)
+      version: 0.0.1
+---
+
+```
+
+You can choose not to provide a version for a data store. If no version is given **latest** is used by default.
+
+### Visualizing data stores within a service
+
+When your service reads/writes to a data store, EventCatalog will visualize this relationship [(see example)](https://demo.eventcatalog.dev/visualiser/services/OrdersService/0.0.3)
+
+![Example](../../../img/services/visualiser-with-data.png)

package/dist/docs/development/guides/{services/adding-to-services/03-entities.md → resources/services/04-add-resources-to-services/03-add-entities-to-services.md}

@@ -1,21 +1,15 @@
 ---
 keywords:
 - EventCatalog services
-sidebar_label: Entities
-title: Adding entities to services
+sidebar_position: 3
+sidebar_label: Add entities to services
+title: Add entities to services
 description: Creating and managing entities within EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-:::tip What are entities?
-Entities are a "**optional**" resource in EventCatalog. You can learn more reading our [entities guide](/docs/development/guides/domains/entities/adding-entities).
-
-:::
-
-<AddedIn version="2.36.0" />
-
-Once you have [created your entities](/docs/development/guides/domains/entities/adding-entities) you can add them to your services.
+Once you have [created your entities](/docs/development/guides/resources/entities/create-entity) you can add them to your services.
 
 To add an entity to a service you need to add the entity to the `entities` array in the service's markdown file.
 
@@ -44,4 +38,6 @@ When a service has entities assigned, EventCatalog generates a dedicated **Entit
 
 The entity map shows each entity as a node and draws edges between entities that reference one another using the `references` field in their properties. This gives you a quick overview of how the domain model is structured inside a service.
 
-To learn how to define relationships between entities, see the [entity map guide](/docs/development/guides/domains/entities/domain-entity-map).
+![Entity Map showing entity relationships](../../entities/img/entity-map.png)
+
+To learn how to define relationships between entities, see [model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships).

package/dist/docs/development/guides/resources/services/04-add-resources-to-services/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Add resources to services",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/add-resources-to-services",
+    "description": "Add messages, data stores, and entities to your services."
+  }
+}

package/dist/docs/development/guides/{services/ownership-and-components/01-owners.md → resources/services/06-ownership-and-components/01-add-service-owners.md}

@@ -1,11 +1,11 @@
 ---
-sidebar_position: 8
+sidebar_position: 1
 keywords:
 - EventCatalog
 - services 
 - owners
-sidebar_label: Owners
-title: Adding service owners
+sidebar_label: Add service owners
+title: Add service owners
 description: Adding owners to services with EventCatalog.
 ---
 
@@ -38,4 +38,3 @@ Assigning owners to your services can provide others with context of who owns th
     EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
 :::
 
-

package/dist/docs/development/guides/{services/ownership-and-components/02-components.md → resources/services/06-ownership-and-components/02-use-components.md}

@@ -1,13 +1,13 @@
 ---
-sidebar_position: 8
+sidebar_position: 2
 keywords:
     - components 
     - domains
-sidebar_label: Components
-title: Components
+sidebar_label: Use components
+title: Use components
 description: Component list for domains 
 ---
 
 You can add custom EventCatalog components to your services.
 
-[See the list of components and how to use them](/docs/development/components/using-components).
+[See the list of components and how to use them](/docs/development/components/using-components).

package/dist/docs/development/guides/resources/services/06-ownership-and-components/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Ownership & components",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/ownership-and-components",
+    "description": "Add owners and custom components to services."
+  }
+}

package/dist/docs/development/guides/{services/versioning-and-lifecycle/01-versioning.md → resources/services/07-versioning-and-lifecycle/01-version-services.md}

@@ -2,8 +2,9 @@
 keywords:
 - versioning
 - services
-sidebar_label: Versioning
-title: Versioning
+sidebar_position: 1
+sidebar_label: Version services
+title: Version services
 description: Learn how to version services
 ---
 
@@ -24,4 +25,4 @@ All content in EventCatalog can be versioned. This allows you to keep historic v
 
 EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/services/Orders/1.0.2 would load the 1.0.2 version of this service).
 
-![Example](../../img/domains/versioned.png)
+![Example](../../../img/domains/versioned.png)

package/dist/docs/development/guides/{services/versioning-and-lifecycle/02-changelog.md → resources/services/07-versioning-and-lifecycle/02-add-changelog.md}

@@ -2,14 +2,15 @@
 keywords:
     - changelog 
     - services
-sidebar_label: Adding a changelog
-title: Service changelogs 
+sidebar_position: 2
+sidebar_label: Add a changelog
+title: Add a changelog
 description: Adding changelogs to your services
 ---
 
-EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services) and [messages](/docs/messages).
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/development/guides/resources/services/introduction) and [messages](/docs/development/guides/resources/messages/what-are-messages).
 
-When you [version a service](/docs/development/guides/services/versioning-and-lifecycle/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that service or versioned service.
+When you [version a service](/docs/development/guides/resources/services/versioning-and-lifecycle/version-services) in EventCatalog, you can also attach a `changelog.mdx` to that service or versioned service.
 
 ### Adding a changelog
 
@@ -49,4 +50,3 @@ Changelogs can provide your team with the context behind the reasons and choices
 Changelogs are visualized by EventCatalog.
 
 
-

package/dist/docs/development/guides/{services/versioning-and-lifecycle/03-deprecating.md → resources/services/07-versioning-and-lifecycle/03-deprecate-services.md}

@@ -3,8 +3,9 @@ keywords:
 - EventCatalog
 - services 
 - owners
-sidebar_label: Deprecating services
-title: Deprecating services
+sidebar_position: 3
+sidebar_label: Deprecate services
+title: Deprecate services
 description: Deprecating services with EventCatalog.
 ---
 
@@ -59,11 +60,11 @@ Deprecated as an object is recommended, as it gives your users more information
 
 Example of resource that will be deprecated:
 
-![Deprecating services](../../img/deprecated/will-be-deprecated.png) 
+![Deprecating services](../../../img/deprecated/will-be-deprecated.png) 
 
 Example of resource that is deprecated:
 
-![Deprecating services](../../img/deprecated/is-deprecated.png) 
+![Deprecating services](../../../img/deprecated/is-deprecated.png) 
 
 #### Demo
 

package/dist/docs/development/guides/resources/services/07-versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/versioning-and-lifecycle",
+    "description": "Version, deprecate, and document changes to services."
+  }
+}