@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/domains/04-add-resources-to-domains/01-add-systems-to-domains.md

@@ -0,0 +1,154 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog domains
+- EventCatalog systems
+sidebar_label: Add systems to domains
+title: Add systems to domains
+description: Add systems to domains so users can move from a business boundary to the software capabilities inside it.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="4.0" />
+
+A [system](/docs/development/guides/systems/introduction) is a collection of resources that work together to perform a function.
+
+Adding systems to your domains helps users move from a business boundary to the software capabilities inside that boundary.
+
+A domain describes the business area or bounded context. A system groups the resources that work together to deliver a capability, such as services, messages, APIs, data stores, flows, or agents.
+
+Systems can live inside a domain folder or outside it. Add them to a domain when you want the domain page to show which systems belong to that business boundary.
+
+## Example domains and systems
+
+For an e-commerce catalog, your domains might look like this:
+
+| Domain | What it represents | Example systems |
+|--------|--------------------|-----------------|
+| `Shopping` | Browsing products, managing carts, and preparing checkout. | `Product Discovery System`, `Cart System`, `Promotion System` |
+| `Ordering` | Taking an order from checkout through fulfilment. | `Checkout System`, `Order Management System`, `Fulfilment System` |
+| `Payments` | Authorizing, capturing, refunding, and reconciling payments. | `Payment Processing System`, `Fraud Review System`, `Refund System` |
+| `Customer` | Customer identity, profiles, preferences, and communication settings. | `Customer Profile System`, `Identity System`, `Notification Preferences System` |
+
+The domain gives users the business boundary. The systems show the software capabilities inside that boundary.
+
+## Recommended structure
+
+When a system clearly belongs to a domain, keep it inside the domain folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'promotion-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This keeps the business model clear: the `Shopping` domain owns the `Cart System` and `Promotion System`.
+
+## Adding systems using frontmatter
+
+To add systems to a domain, add a `systems` array to the domain frontmatter.
+
+```md title="/domains/Shopping/index.mdx (example)"
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+summary: |
+  The Shopping domain owns the customer's path to purchase.
+systems:
+  - id: cart-system
+    version: 1.0.0
+  - id: promotion-system
+    version: 1.0.0
+---
+
+## Overview
+
+The Shopping domain is responsible for everything between browsing and buying.
+```
+
+The `systems` field tells EventCatalog which systems belong to the domain.
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the system.
+
+## Showing systems in context
+
+You can add `<ContextDiagram />` to the domain page to show the systems in that domain and how they relate to each other.
+
+![Systems context map showing systems and actors inside a domain](./img/systems-in-domain-context.png)
+
+```md title="/domains/Shopping/index.mdx (example)"
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+systems:
+  - id: cart-system
+  - id: promotion-system
+---
+
+## System context
+
+<ContextDiagram />
+```
+
+Use this view when you want readers to understand the systems inside a domain before they drill into lower-level resources.
+
+## Linking to systems from domain docs
+
+You can link to systems from domain Markdown using resource references.
+
+```md
+The [[system|cart-system]] owns cart state and checkout.
+```
+
+If you want systems to act as entry points from the domain page, you can also use tiles or regular Markdown links.
+
+## When to add systems to a domain
+
+Add systems to a domain when the system is part of that domain's business boundary.
+
+For example:
+
+- `Shopping` contains `Cart System` and `Promotion System`.
+- `Ordering` contains `Checkout System` and `Order Management System`.
+- `Customer` contains `Customer Management System` and `Identity Provider`.
+
+If a system is shared across multiple domains, you can keep it outside the domain folder and still reference it from the domain frontmatter.
+
+For the complete system fields and file structure, see the [systems reference](/docs/development/guides/systems/reference).

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

@@ -1,15 +1,17 @@
 ---
-sidebar_position: 3
+sidebar_position: 2
 keywords:
 - EventCatalog domains
-sidebar_label: Adding services to domains
-title: Adding services to domains
+sidebar_label: Add services to domains
+title: Add services to domains
 description: Creating and managing domains within EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-Adding [services](/docs/development/guides/services/introduction) to your domains is a great way to group services within a particular domain.
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component. A service can produce/consume messages or implement an API specification (e.g OpenAPI, AsyncAPI, GraphQL).
+
+Adding [services](/docs/development/guides/resources/services/introduction) to your domains is a great way to group services within a particular domain.
 
 When adding services to your domain EventCatalog will:
 
@@ -82,36 +84,3 @@ When you view your domain in EventCatalog, the services will be visualized for y
 
 ![Example](../../img/domains/visualiser.png)
 
-
-
-## Making changes and versioning
-
-You can make as many changes as you want, but if you are adding/removing services you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why services are coming in/out of a particular domain.
-
-## Add agents to a domain
-
-<AddedIn version="3.41.0" />
-
-[Agents](/docs/development/guides/agents/introduction) can be attached to a domain the same way services can. Add an `agents` array to your domain's frontmatter:
-
-```md title="/domains/Payment/index.mdx (example)"
----
-id: Payment
-name: Payment Domain
-version: 0.0.1
-services:
-  - id: PaymentService
-    version: 0.0.1
-agents:
-  - id: FraudReviewAgent
-    version: 0.0.1
-  # version is optional — latest is used if omitted
-  - id: AnotherAgent
----
-
-<!-- Markdown content... -->
-
-```
-
-EventCatalog will show the agents in the domain sidebar and include them in the domain visualiser alongside services.
-

package/dist/docs/development/guides/domains/{02-creating-domains/04-adding-messages-to-domains.md → 04-add-resources-to-domains/03-add-messages-to-domains.md}

@@ -1,18 +1,16 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 keywords:
 - EventCatalog domains
 - domain messages
-sidebar_label: Adding messages to domains
-title: Adding messages to domains
+sidebar_label: Add messages to domains
+title: Add 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.
+Adding [messages](/docs/development/guides/resources/messages/what-are-messages) 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).
 

package/dist/docs/development/guides/domains/{02-creating-domains/05-adding-data-products-to-domains.md → 04-add-resources-to-domains/04-add-data-products-to-domains.md}

@@ -1,10 +1,11 @@
 ---
 sidebar_position: 5
+sidebar_class_name: hidden
 keywords:
   - EventCatalog domains
   - domain data products
-sidebar_label: Adding data products to domains
-title: Adding data products to domains
+sidebar_label: Add data products to domains
+title: Add data products to domains
 description: Organize analytics and data assets within domain boundaries.
 ---
 
@@ -12,7 +13,7 @@ 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.
+Adding [data products](/docs/development/guides/resources/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.
 
@@ -101,5 +102,5 @@ You can make as many changes as you want, but if you are adding or removing data
 
 ## See also
 
-- [Data products guide](/docs/development/guides/data-products/introduction)
-- [Adding data products to domains](/docs/development/guides/data-products/adding-to-domains)
+- [Data products guide](/docs/development/guides/resources/data-products/introduction)
+- [Adding data products to domains](/docs/development/guides/domains/add-resources-to-domains/add-data-products-to-domains)

package/dist/docs/development/guides/domains/04-add-resources-to-domains/05-add-entities-to-domains.md

@@ -0,0 +1,115 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 4
+sidebar_label: Add entities to domains
+title: Add entities to domains
+description: Creating and managing entities within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Once you have [created your entities](/docs/development/guides/resources/entities/create-entity) you can add them to your domains.
+
+To add an entity to a domain, add the entity to the `entities` array in the domain's markdown file.
+
+```mdx title="/domains/Orders/index.mdx"
+
+---
+id: Orders
+name: Orders
+version: 1.0.0
+entities:
+  - id: Order
+    version: 1.0.0
+  - id: OrderItem
+    version: 1.0.0
+---
+
+Your domain markdown...
+
+```
+
+## Visualize domain entities
+
+<AddedIn version="2.49.0" />
+
+When a domain has entities assigned, EventCatalog can generate an entity map for that domain.
+
+The entity map helps teams understand the domain model at a glance. It shows:
+
+- The entities inside the domain
+- The relationships between those entities
+- Which entities are owned by the current domain
+- Entities referenced from other domains
+
+Entities that are referenced from another domain are shown as **yellow**.
+
+![Entity Map](../../resources/entities/img/entity-map.png)
+
+## View the entity map in the visualizer
+
+EventCatalog creates a dedicated entity map visualizer route for domains:
+
+```txt
+/visualiser/domains/{id}/{version}/entity-map
+```
+
+For services, the route is:
+
+```txt
+/visualiser/services/{id}/{version}/entity-map
+```
+
+When a domain or service has entities assigned, an **Entity Map** link appears automatically in the resource sidebar under the visualizer section.
+
+## Embed the entity map on a page
+
+You can also embed the entity map of a domain on any page in your catalog using the `<EntityMap />` component.
+
+```mdx
+<EntityMap id="Orders" title="Orders Domain Entity Map" />
+```
+
+![Entity Map Component](../../resources/entities/img/entity-map-component.png)
+
+## Create relationships between entities
+
+Entity maps become more useful when your entities reference each other.
+
+Use the optional reference fields on entity properties:
+
+- `references`: The entity you want to reference, for example `Order`
+- `relationType`: The type of relationship, for example `hasOne`, `hasMany`, or `belongsTo`
+- `referencesIdentifier`: The property in the referenced entity used to establish the relationship, for example `orderId`
+
+For example, an `OrderItem` can reference an `Order` through `orderId`.
+
+```yaml title="/domains/Orders/entities/OrderItem/index.mdx"
+---
+id: OrderItem
+name: OrderItem
+version: 1.0.0
+identifier: orderItemId
+summary: Represents a single item within a customer's order.
+
+properties:
+  - name: orderItemId
+    type: UUID
+    required: true
+    description: Unique identifier for the order item
+  - name: orderId
+    type: UUID
+    required: true
+    description: Identifier for the parent Order
+    references: Order
+    relationType: hasOne
+    referencesIdentifier: orderId
+---
+```
+
+This configuration generates an entity map that visually shows the relationship between `OrderItem` and `Order`.
+
+![Entity Map showing a relationship between OrderItem and Order](../../resources/entities/img/simple-entity-map.png)
+
+More information on entity reference fields can be found in the [entities reference](/docs/development/guides/resources/entities/reference).

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

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

package/dist/docs/development/guides/domains/{08-domain-integration-map.md → 06-visualize-domains/01-domain-integration-map.md}

@@ -1,10 +1,11 @@
 ---
-sidebar_position: 7
+sidebar_position: 1
+sidebar_class_name: hidden
 keywords:
     - domain integration map
     - domains
-sidebar_label: Domain Integration Map
-title: Domain Integration Map
+sidebar_label: Domain integration map
+title: Domain integration map
 description: Component list for domains 
 ---
 
@@ -14,7 +15,7 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 The **GlobalDomain Integration Map** (see [demo](https://demo.eventcatalog.dev/visualiser/domain-integrations)) is a powerful visualization feature in EventCatalog that provides a high-level view of your domains, services and messages. It displays domains containing their services, with cross-domain message flows clearly visualized as connections between domains.
 
-![Example](../img/domains/domain-integration.png)
+![Example](../../img/domains/domain-integration.png)
 
 This feature is particularly valuable for organizations practicing Domain-Driven Design (DDD) and event-driven architecture, where understanding the interactions between domains is crucial for system design and evolution.
 
@@ -37,5 +38,3 @@ To see the Domain integration map, you need at least one domain in your EventCat
 You can a demo of the Domain Integration Map in the [EventCatalog Demo](https://demo.eventcatalog.dev/visualiser/domain-integrations).
 
 
-
-

package/dist/docs/development/guides/domains/06-visualize-domains/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Visualize domains",
+  "position": 6,
+  "className": "hidden",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/domains/visualize-domains",
+    "description": "Visualize domain relationships, integrations, and entities."
+  }
+}

package/dist/docs/development/guides/domains/{04-versioning-and-changelogs/01-versioning.md → 07-version-domains.md}

@@ -1,10 +1,11 @@
 ---
-sidebar_position: 5
 keywords:
 - versioning
 - domains
-sidebar_label: Versioning
-title: Versioning
+sidebar_position: 7
+sidebar_class_name: hidden
+sidebar_label: Version domains
+title: Version domains
 description: Learn how to version domains
 ---
 
@@ -35,6 +36,4 @@ Example would when new developers come on board, maybe they are interested in a
 
 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)
-
-
+![Example](../img/domains/versioned.png)

package/dist/docs/development/guides/domains/{04-versioning-and-changelogs/02-changelog.md → 08-add-changelog.md}

@@ -1,16 +1,17 @@
 ---
-sidebar_position: 6
+sidebar_position: 8
+sidebar_class_name: hidden
 keywords:
     - changelog 
     - domains
-sidebar_label: Adding a changelog
-title: Domain changelogs 
+sidebar_label: Add a changelog
+title: Add a changelog
 description: Adding changelogs to your domains
 ---
 
-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 domain](/docs/development/guides/domains/versioning-and-changelogs/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that domain or version.
+When you [version a domain](/docs/development/guides/domains/version-domains) in EventCatalog, you can also attach a `changelog.mdx` to that domain or version.
 
 ### Adding a changelog
 
@@ -49,5 +50,3 @@ Changelogs can provide your team with the context behind the reasons and choices
 
 Changelogs are visualized by EventCatalog.
 
-
-