@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/domains/02-creating-domains/04-adding-messages-to-domains.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog domains
+- domain messages
+sidebar_label: Adding messages to domains
+title: Adding messages to domains
+description: Document event flows at the domain level.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.7.0" />
+
+Adding [messages](/docs/development/guides/messages/overview) to your domains allows you to document which messages are published and consumed by your domain.
+
+Some teams may prefer to document messages at the domain level, and have the service reference the domain messages (implementation of the domain messages).
+
+These can be known as "domain events", "external events" or "integration events", it's really up to you how you want to model them.
+
+These messages can live anywhere in your catalog, at the domain level or within the service folder. You just need to reference them in your domain frontmatter.
+
+## Adding messages using frontmatter
+
+To add messages to a domain you need to define them in either the `sends` or `receives` array within your domain frontmatter API.
+
+- sends: messages this domain publishes
+- receives: messages this domain consumes
+
+You need to add the `id` of the message and optionally the `version` of the message.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: Orders
+... # other domain frontmatter
+receives:
+    # id of the message this domain 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 domain sends
+    - id: OrderCreated
+      version: 2.0.1
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `sends` and `receives` fields in your domain tell EventCatalog which messages this domain either publishes or consumes.
+
+In the example above we can see that the `Orders` domain receives the `PaymentProcessed` message and sends the `OrderCreated` message.
+
+## Domain vs service level messaging
+
+Messages can be documented at either the domain level or service level. This is flexible and it's up to you which you prefer.
+
+- Service Level
+  - You document messages a particular service publishes or consumes.
+- Domain Level
+  - You document messages that are published or consumed by a domain.
+
+Remember you can also use both approaches together, and your messages can live anywhere in your catalog.
+
+## Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing messages in your domains.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: Orders
+... # other domain frontmatter
+receives:
+    # Domain receives a message called PaymentProcessed
+    # The latest minor/patch version of this event will be used
+    - id: PaymentProcessed
+      version: 1.x.x
+sends:
+    # Domain sends a message called OrderCreated
+    # This pulls the latest patch version of OrderCreated
+    - id: OrderCreated
+      version: 2.0.x
+    # Domain sends a message called OrderCancelled
+    # This pulls the latest minor/patch version of OrderCancelled
+    - id: OrderCancelled
+      version: >1.0.1
+---
+
+<!-- Markdown content... -->
+
+```
+
+Although it's recommended to link to a version of a message it is now optional. If no version is given the latest version is used by default.
+
+## Visualizing messages within a domain
+
+Messages are shown in the sidebar of your domain under "Publishes Messages" and "Consumes Messages" sections. There is currently no visualizer support for messages at the domain level.
+
+_Coming soon: Visualizer support for messages at the domain level._
+
+## Making changes and versioning
+
+You can make as many changes as you want, but if you are adding or removing messages you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why messages are coming in or out of a particular domain.

package/dist/docs/development/guides/domains/02-creating-domains/05-adding-data-products-to-domains.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 5
+keywords:
+  - EventCatalog domains
+  - domain data products
+sidebar_label: Adding data products to domains
+title: Adding data products to domains
+description: Organize analytics and data assets within domain boundaries.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Adding [data products](/docs/development/guides/data-products/introduction) to your domains allows you to document which analytical assets and data pipelines belong to a domain.
+
+Data products can live anywhere in your catalog, at the domain level or in their own folder. You just need to reference them in your domain frontmatter.
+
+## Adding data products using frontmatter
+
+To add data products to a domain you need to add them to the `data-products` array within your domain frontmatter API.
+
+```md title="/domains/E-Commerce/index.mdx (example)"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  # id of the data product you want to add
+  - id: order-analytics
+    # (optional) The version of the data product you want to add.
+    # If no version is given the latest version of the data product will be used.
+    version: 1.0.0
+
+  # version is optional for all data products
+  - id: payment-analytics
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `data-products` field in your domain tells EventCatalog which data products belong to this domain.
+
+In the example above we can see that the `order-analytics` and `payment-analytics` data products belong to the `e-commerce` domain.
+
+## Using semver versioning
+
+<AddedIn version="3.8.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing data products in your domains.
+
+```md title="/domains/E-Commerce/index.mdx (example)"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  # Latest minor/patch version of order-analytics will be used
+  - id: order-analytics
+    version: 1.x.x
+  # Latest patch version of payment-analytics will be used
+  - id: payment-analytics
+    version: 2.0.x
+  # Latest version of fulfillment-metrics will be used
+  - id: fulfillment-metrics
+---
+
+<!-- Markdown content... -->
+
+```
+
+Although it's recommended to link to a version of a data product it is now optional. If no version is given the latest version is used by default.
+
+## Visualizing data products within a domain
+
+Data products are shown in the sidebar of your domain under a "Data Products" section. You can also display them in a grid alongside other domain resources.
+
+```md title="/domains/E-Commerce/index.mdx"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  - id: order-analytics
+  - id: payment-analytics
+---
+
+## Data Products
+
+Our analytical capabilities include order metrics, payment insights, and fulfillment KPIs.
+
+```
+
+## Making changes and versioning
+
+You can make as many changes as you want, but if you are adding or removing data products you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why data products are coming in or out of a particular domain.
+
+## See also
+
+- [Data products guide](/docs/development/guides/data-products/introduction)
+- [Adding data products to domains](/docs/development/guides/data-products/adding-to-domains)

package/dist/docs/development/guides/domains/02-creating-domains/_category_.json

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

package/dist/docs/development/guides/domains/03-ownership-and-language/01-owners.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+
+keywords:
+- EventCatalog
+- domain 
+- owners
+sidebar_label: Adding domain owners
+title: Adding domain owners
+description: Adding owners to domains with EventCatalog.
+---
+
+You can assign owners to your domains to provide context of who owns this domain and how to contact them.
+
+Owners in EventCatalog are either [**users**](/docs/development/guides/owners/users/introduction) or [**teams**](/docs/development/guides/owners/teams/introduction) and are **optional**.
+
+## Adding owners to a domain
+
+To add owners to a domain you need to add them to the `owners` array within your domain frontmatter API.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your domains can provide others with context of who owns this domain and how to contact them.
+
+

package/dist/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog domains
+sidebar_label: Ubiquitous language
+title: Ubiquitous language
+description: Creating a Ubiquitous-language dictionary for your domain
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.16.0" />
+
+Ubiquitous Language is a shared language that is used by all stakeholders in a project/domain to improve communication and reduce misunderstandings.
+
+In EventCatalog you can define a dictionary of ubiquitous language terms for your domain, this can help your teams understand the language used in your domain and models used in your architecture.
+
+## Using ubiquitous language in EventCatalog
+
+To add a ubiquitous language dictionary, create a new file within your domain folder with the name `ubiquitous-language.mdx`.
+
+- `/domains/{Domain Name}/ubiquitous-language.mdx`
+
+The contents of the file should be a list of terms used in your domain. 
+
+Each term should have a name, summary, description and icon. The icon is optional and can be used to visually represent the term. You can find a list of icons [here](https://lucide.dev/).
+
+```md title="/domains/Orders/ubiquitous-language.md"
+---
+dictionary:
+  - id: Purchase Order
+    name: Purchase Order
+    summary: "A mystical document issued by a buyer to a seller, here indicating the types, quantities, and agreed prices for enchanted products or services."
+    description: |
+      A purchase order (PO) is a magical document that initiates the buying process between mystical entities. It protects both buyer and seller by clearly documenting the transaction details. Key components include:
+
+      - Unique PO number for tracking
+      - Detailed item specifications and quantities
+      - Agreed prices and payment terms
+      - Delivery requirements and timelines
+      - Terms and conditions of the purchase
+
+      POs are essential for budget control, audit trails, and inventory management. They help prevent unauthorized purchases and provide a clear record for accounting and reconciliation purposes.
+    icon: FileText 
+  - id: Order Line
+    name: Order Line
+    summary: "An individual enchanted item within a purchase order, representing a specific magical product or service being ordered."
+    description: |
+      Order lines are the fundamental building blocks of any purchase order. Each line represents a distinct item or service and contains critical information for order fulfillment:
+
+      - Product identifier (SKU or part number)
+      - Quantity ordered
+      - Unit price and total line value
+      - Special handling instructions
+      - Required delivery date
+
+      Order lines drive warehouse picking operations, shipping processes, and financial calculations. They are essential for tracking partial shipments and managing order modifications.
+    icon: ListOrdered
+---
+
+```
+
+### Viewing the ubiquitous language in EventCatalog
+
+When you add a ubiquitous language dictionary to your domain, it will automatically appear in the sidebar of the domain.
+
+![Example](../../img/domains/ubiquitous-lang-sidebar.png)
+<a class="block" href="https://demo.eventcatalog.dev/docs/domains/Orders/language">View demo</a>
+
+Clicking on a term in the Domain Language explorer will open that term in a new page. 
+
+
+
+
+

package/dist/docs/development/guides/domains/03-ownership-and-language/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Ownership & language",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/ownership-and-language"
+  }
+}

package/dist/docs/development/guides/domains/04-versioning-and-changelogs/01-versioning.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 5
+keywords:
+- versioning
+- domains
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version domains
+---
+
+**All content in EventCatalog can be versioned**.
+
+This allows you to keep historic versions of content which can give context to users why things are changing.
+
+:::tip Tip: Versioning can be great for context
+
+Versioning in EventCatalog is a great way to track changes over time. At any point users using EventCatalog can look back in time and understand what changes have been made to domains, services and messages. This gives extra context that is usually missed.
+
+Example would when new developers come on board, maybe they are interested in a particular domain, maybe they want to understand the history of this domain, where it started and how it came to be what it is today. Versioning allows you to capture this context.
+
+:::
+
+## How to version a domain
+
+1. Create a `/versioned` directory inside the `/domains` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/domains/Orders/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/domains/Orders/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the domain.
+    - Example `/domains/Orders/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+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/domains/Orders/1.0.2 would load the 1.0.2 version of this domain).
+
+![Example](../../img/domains/versioned.png)
+
+

package/dist/docs/development/guides/domains/04-versioning-and-changelogs/02-changelog.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 6
+keywords:
+    - changelog 
+    - domains
+sidebar_label: Adding a changelog
+title: Domain changelogs 
+description: Adding changelogs to your domains
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services) and [messages](/docs/messages).
+
+When you [version a domain](/docs/development/guides/domains/versioning-and-changelogs/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that domain or version.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your domain (or versioned domain)
+    - example `/domains/{Domain}/changelog.mdx`
+    - versioned example `/domains/{Domain}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/domains/Orders/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: ⭐️ JSON Schema
+      backgroundColor: purple
+      textColor: purple
+---
+
+### Added new service to the domain
+
+Added the Payment service into the domain.
+
+``` 
+
+Navigate to your change log page for your domain (example [/docs/domains/Orders/0.0.2/changelog](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.2/changelog)) or **click on the Changelog button** on your domain page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your domain and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
+

package/dist/docs/development/guides/domains/04-versioning-and-changelogs/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Versioning & changelogs",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/domains/versioning-and-changelogs"
+  }
+}

package/dist/docs/development/guides/domains/05-entities/01-introduction.md

@@ -0,0 +1,24 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: What are entities?
+title: What are entities?
+description: What are entities? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.36.0" />
+
+In Domain-Driven Design, an entity is an object with a unique identity that stays the same over time, even if its data changes. It’s defined by this identity, not just its properties. For example, a `Customer` with a unique ID is an entity, even if their name or address changes.
+
+In Domain-Driven Design, entities are the core building blocks of a domain—they represent key concepts or things within that domain that have a unique identity. The domain defines the business logic and rules, and entities bring that logic to life by modeling real-world objects or roles, like `Order`, `Customer`, or `Invoice`. Each entity lives within a bounded context of the domain, ensuring it behaves consistently according to that part of the business.
+
+**In EventCatalog entities are optional.**, if you don't want to add entity documentation you can skip this resource.
+
+### How do entities work in EventCatalog?
+
+Entities are a "**optional**" resource in EventCatalog and like every other resource in EventCatalog they are defined in markdown files.
+
+Entities can be added to your `domains` and `services`.
+

package/dist/docs/development/guides/domains/05-entities/02-adding-entities.md

@@ -0,0 +1,157 @@
+---
+keywords:
+- EventCatalog entities
+sidebar_label: Creating an entity
+title: Creating entities
+description: Creating and managing entities within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.36.0" />
+
+Entities are markdown files in EventCatalog, they have unique ids and can be versioned.
+
+Entities can be assigned to domains and/or services.
+
+You can read the Entity API documentation [here](/docs/api/entity-api).
+
+### What do entities look like in EventCatalog?
+
+![Example](./img/entity-example.png)
+
+Entity visualization
+
+![Entity Map](./img/entity-map.png)
+
+[View Demo of an OrderItem entity for an Orders domain &rarr;](https://demo.eventcatalog.dev/docs/entities/OrderItem/1.0.0)
+
+## Adding a new entity
+
+To add a new entity create a new folder within the `/domains` or `/services` folder with an `index.mdx` file.
+
+**Creating an entity in a domain:**
+- `/domains/{Domain Name}/entities/{Entity Name}/index.mdx` 
+  - (example `/domains/Orders/entities/Order/index.mdx`)
+
+**Creating an entity in a service:**
+- `/services/{Service Name}/entities/{Entity Name}/index.mdx`
+  - (example `/services/PaymentService/entities/Payment/index.mdx`)
+
+The `index.mdx` contents are split into two sections, **frontmatter** and the **markdown content**.
+
+
+_Here is an example of what a entity markdown file may look like._
+
+```md title="/domains/Orders/entities/Order/index.mdx (example)"
+---
+# the id of the entity (used in EventCatalog)
+id: Order
+# the name of the entity
+name: Order
+# the version of the entity
+version: 1.0.0
+# whether the entity is an aggregate root (optional)
+aggregateRoot: true
+# a summary of the entity (optional)
+summary: Represents a customer's request to purchase products or services.
+# the properties of the entity (optional)
+properties:
+  - name: orderId
+    type: UUID
+    required: true
+    description: Unique identifier for the order
+  - name: customerId
+    type: UUID
+    required: true
+    description: Identifier for the customer placing the order
+  - name: orderDate
+    type: DateTime
+    required: true
+    description: Date and time when the order was placed
+  - name: status
+    type: string
+    required: true
+    description: Current status of the order (e.g., Pending, Processing, Shipped, Delivered, Cancelled)
+    enum: ['Pending', 'Processing', 'Shipped', 'Delivered', 'Cancelled']
+  - name: orderItems
+    type: array
+    items:
+      type: OrderItem # Assuming an OrderItem entity exists
+    required: true
+    description: List of items included in the order
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: Total monetary value of the order
+  - name: shippingAddress
+    type: Address # Assuming an Address value object or entity exists
+    required: true
+    description: Address where the order should be shipped
+---
+
+## Overview
+
+The Order entity captures all details related to a customer's purchase request. It serves as the central aggregate root within the Orders domain, coordinating information about the customer, products ordered, payment, and shipping.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Customer:** Each order belongs to one `Customer` (identified by `customerId`).
+*   **OrderItem:** An order contains one or more `OrderItem` entities detailing the specific products and quantities.
+*   **Payment:** An order is typically associated with a `Payment` entity (not detailed here).
+*   **Shipment:** An order may lead to one or more `Shipment` entities (not detailed here).
+
+## Examples
+
+*   **Order #12345:** A customer orders 2 units of Product A and 1 unit of Product B, to be shipped to their home address. Status is 'Processing'.
+*   **Order #67890:** A customer places a large order for multiple items, requiring special shipping arrangements. Status is 'Pending' until payment confirmation.
+
+```
+
+Once you add you new entity, you need to add it to the domain.
+
+```md title="/domains/Orders/index.mdx"
+---
+# the id of the domain (used in EventCatalog)
+id: Orders
+# the name of the domain
+name: Orders
+# Add your entities here
+entities:
+  - id: Order
+    # Optional, if not provided the latest version will be used
+    version: 1.0.0
+---
+
+This is your domain markdown....
+
+```
+
+Once your entity is defined and added to the domain, you can navigate to the entity through domain navigation.
+
+To learn more about entities and how to use them, you can read the Entity API documentation [here](/docs/api/entity-api).
+
+## Adding markdown content
+
+With **entities** you can write any Markdown you want and it will render on your page. Every entity gets its own page.
+
+:::tip
+Think about writing a blog. EventCatalog is just markdown. Write and use it how you like, and the website will render your content!
+:::
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.
+
+To find out more read the [entity components list](/docs/development/components/using-components).
+
+### Tips for entity content
+
+It's entirely up to you what you want to add to your entities markdown content but here are a few things you might want to consider.
+
+- Add a summary of the entity
+- Add a diagram of the entity
+- Add examples of the entity
+- Add a table of the entity properties using the `<EntityPropertiesTable />` component
+

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

@@ -0,0 +1,30 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: Adding entities to domains
+title: Adding entities to domains
+description: Creating and managing entities within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.36.0" />
+
+Once you have [created your entities](/docs/development/guides/domains/entities/adding-entities) you can add them to your domains.
+
+To add an entity to a domain you need to add the entity to the `entities` array in the domain's markdown file.
+
+```mdx title="/domains/Orders/index.mdx"
+
+---
+id: OrderItem
+name: OrderItem
+version: 1.0.0
+entities:
+  - id: OrderItem
+    version: 1.0.0
+---
+
+Your domain markdown...
+
+```