@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/services/02-adding-services.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating a service
+title: Creating services
+description: Creating and managing services within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Services in EventCatalog are a great way to document which parts of your systems send and receive messages.
+
+You can also add specifications [(OpenAPI, AsyncAPI, GraphQL)](/docs/development/guides/services/adding-to-services/openapi) to your services.
+
+### What do services look like in EventCatalog?
+
+![Example](../img/services/service-example.png)
+
+[View Demo of an Orders service →](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3)
+
+## Adding a new service
+
+To add a new service create a new folder within the `/services` folder with an `index.mdx` file.
+
+- `/services/{Service Name}/index.mdx` 
+  - (example `/services/Orders/index.mdx`)
+
+You can also specify services in your domains folder.
+- `/domains/{Domain Name}/services/{Service Name}/index.mdx` 
+  - (example `/domains/Orders/services/OrdersService/index.mdx`)
+
+_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.
+
+## Adding specifications to your service
+
+You can add GraphQL, OpenAPI or AsyncAPI specifications to your service.
+
+You can read more about adding specifications to your service [here](/docs/development/guides/services/adding-to-services/openapi).
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the service. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: Orders
+name: Orders
+version: 0.0.1
+styles:
+  icon: /icons/languages/dotnet.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/logo.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/nodejs`). [Simple Icons CDN](https://cdn.simpleicons.org) is a useful source for brand logos.
+

package/dist/docs/development/guides/services/03-creating-external-systems.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog services
+- External systems
+sidebar_label: Creating an external system
+title: Creating external systems
+description: Model third-party services like Stripe, Twilio, or Snowflake as external systems in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.28.0" />
+
+External systems 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 Systems" section in the sidebar (or "External Integrations" when inside a domain).
+
+Creating an external system 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 system. 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 system 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.
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` to brand your external system with its real logo. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/services/Stripe/index.mdx (example)"
+---
+id: Stripe
+name: Stripe
+version: 1.0.0
+externalSystem: true
+styles:
+  icon: https://cdn.simpleicons.org/stripe
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/stripe.svg`) or an absolute URL. [Simple Icons CDN](https://cdn.simpleicons.org) is a convenient source for brand logos — use `https://cdn.simpleicons.org/<slug>` where `<slug>` matches the service name.

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

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

package/dist/docs/development/guides/services/adding-to-services/01-messages.md

@@ -0,0 +1,229 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: Messages
+title: Adding messages to services
+description: Understanding how to add messages to services.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+EventCatalog supports different types of messages ([commands](/docs/development/guides/messages/commands/introduction), [events](/docs/development/guides/messages/events/introduction) and [queries](/docs/development/guides/messages/queries/introduction)).
+
+A service in EventCatalog can **receive** or **send** messages. 
+
+A service can also **send** and **receive** messages through channels.
+
+![Example](../../img/services/example.png)
+
+
+:::info What about producers and consumers?
+
+If you are coming from an event-driven architecture you will be familiar with the terms producers and consumers. Producers produce events and consumers consume them.
+
+
+EventCatalog services can be either producers or consumers or both. For example if a service receives an event (type of message) it is the consumer, if it sends an event (type of message) it is the producer.
+
+
+The idea of **sends** and **receives** comes from the [AsyncAPI specification](https://www.asyncapi.com/blog/release-notes-3.0.0) and gives flexibility to support other types of messages (commands and queries).
+
+:::
+
+To add messages to your service you first have to define your messages.
+
+Once you have messages defined in your Catalog you can reference them within your service.
+
+## Adding messages to your service
+
+To add messages to a service you need to define them in either the **sends** or **receives** array within your service frontmatter API.
+
+You need to add the `id` of the message and optionally the `version` of the message.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # id of the message this service receives
+    - id: PaymentProcessed
+    # (optional) The version of the message you want to add.
+    # 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
+    - id: OrderProcessed
+      version: 2.0.1
+---
+
+<!-- Markdown contents... -->
+
+```
+
+The **receives** and **sends** fields in your service tell EventCatalog which messages this service either consumes or publishes.  
+
+:::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.
+:::
+
+### Declaring field dependencies
+
+<AddedIn version="3.24.0" />
+
+You can declare which specific fields of a message your service depends on by adding a `fields` array to any `receives` entry.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+  - id: PaymentProcessed
+    version: 1.0.0
+    fields:
+      - orderId
+      - amount
+      - currency
+---
+```
+
+Declaring fields is optional. When at least one service declares fields for a message, EventCatalog generates a **Field Usage** page for that message showing which services depend on each field. You can read more in the [Field Usage guide](/docs/development/guides/schemas/field-usage).
+
+### Routing messages through channels
+
+You can also route your messages through channels. Examples of these could be your brokers, queues, topics, etc.
+
+To do this you can 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:
+      - 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:
+      - id: payments.events
+---
+```
+
+You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/channels/introduction).
+
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing your services in your domains.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+services:
+    # Latest minor version of PaymentsService will be added
+    - id: PaymentsService
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: NotificationsService
+      version: ^1.0.1
+    # Latest version of this service will be shown by default.
+    - id: PaymentsService
+---
+
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # Service receives a message called PaymentProcessed
+    # The latest minor/patch version of this event will be used
+    - id: PaymentProcessed
+      version: 1.x.x
+sends:
+    # Service sends a message called OrderProcessed
+    # This pulls the latest patch version of OrderProcessed
+    - id: OrderProcessed
+      version: 2.0.x
+    # Service sends a message called OrderCancelled
+    # This pulls the latest minor/patch version of OrderCancelled
+    - id: OrderCancelled
+      version: >1.0.1
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Although it's recommended to link to a version of a message it is now optional. If no version is given **latest** is used by default.
+
+### 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/services/adding-to-services/02-datastores.md

@@ -0,0 +1,77 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: Data stores
+title: Adding data stores to services
+description: Adding data stores to services
+slug: adding-data-stores-to-services
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+[Data stores](/docs/development/guides/data/introduction) in EventCatalog are a great way to document which data stores your services write to or read from.
+
+:::info What are data stores?
+  Data stores are containers that hold data in your architecture (e.g. databases, caches, object stores, search indexes, etc).
+
+  You can read more about data stores [here](/docs/development/guides/data/introduction).
+:::
+
+
+## Specifying read/write relationships to data stores
+
+To document the read/write relationships to data stores you need to specify the data stores in 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
+      version: 0.0.1
+---
+
+```
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing your data stores in your services.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+writesTo:
+    # Latest minor version of OrdersDatabase will be added
+    - id: OrdersDatabase
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: ProductRedisCache
+      version: ^1.0.1
+    # Latest version of this data store will be shown by default.
+    - id: OrdersDatabase
+---
+<!-- Markdown contents... -->
+
+```
+
+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 data stores get added within your services EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.
+
+![Example](../../img/services/visualiser-with-data.png)
+
+You can see an example of this [here](https://demo.eventcatalog.dev/visualiser/services/OrdersService/0.0.3)

package/dist/docs/development/guides/services/adding-to-services/03-entities.md

@@ -0,0 +1,47 @@
+---
+keywords:
+- EventCatalog services
+sidebar_label: Entities
+title: Adding 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.
+
+To add an entity to a service you need to add the entity to the `entities` array in the service's markdown file.
+
+```md title="/services/PaymentService/index.mdx"
+
+---
+id: PaymentService
+name: PaymentService
+version: 1.0.0
+# This assumes you have an entity called Payment
+entities:
+  - id: Payment
+    # Optional, if not provided the latest version will be used
+    version: 1.0.0
+---
+
+Your service markdown...
+
+```
+
+## Visualize entity relationships
+
+<AddedIn version="3.25.1" />
+
+When a service has entities assigned, EventCatalog generates a dedicated **Entity Map** page in the visualizer at `/visualiser/services/{id}/{version}/entity-map`. A link to this view appears automatically in the service sidebar under the visualizer section.
+
+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).

package/dist/docs/development/guides/services/adding-to-services/04-openapi.md

@@ -0,0 +1,97 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: OpenAPI specifications
+title: Adding OpenAPI specifications
+description: Attach an OpenAPI specification to your service and render them in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.6.0" />
+
+Services in EventCatalog allow you to render OpenAPI specifications ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/spec/openapi-v1)).
+
+![Example](../../img/services/openapi-spec.png)
+
+You have two options for adding OpenAPI specifications to your service:
+
+- [Adding OpenAPI files to EventCatalog](#adding-openapi-specifications-to-eventcatalog)
+- [Reference the OpenAPI file from a remote URL](#reference-the-openapi-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your OpenAPI files?
+  Did you know you can automate your documentation, visualizations and owners using your OpenAPI Files?
+
+  We have a [OpenAPI plugin](/docs/plugins/openapi/intro) that can generate your catalog from your OpenAPI files, transforming your operations into 
+  commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding OpenAPI files to EventCatalog
+
+This option is useful if you want to keep your OpenAPI files in your EventCatalog.
+
+To add an OpenAPI file to your service you will need to include the file itself inside the service directory.
+
+- `/services/{Service Name}/openapi.yml` 
+  - (example `/services/Orders/openapi.yml`)
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: openapi
+      # Path to the OpenAPI file relative to the service directory
+      path: openapi.yml
+      # Friendly name for the specification
+      name: OpenAPI Specification
+---
+```  
+
+## Reference the OpenAPI file from a remote URL
+
+<AddedIn version="2.61.2" />
+
+This can be useful if you want to keep your OpenAPI files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your specifications changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: openapi
+      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-openapi/refs/heads/main/examples/product-api/openapi.yml
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+## Multiple OpenAPI Files
+
+<AddedIn version="2.39.1" />
+
+If your service exposes multiple APIs or versions of the same API, you can assign multiple OpenAPI files to a single service.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: openapi
+      path: openapi-v1.yml
+      name: v1
+    - type: openapi
+      path: openapi-v2.yml
+      name: v2
+---
+```
+
+This will render a list of specification files on your service page and navigation bar.
+
+![Example](../../img/services/openapi-many.png)
+
+
+