@eventcatalog/core 4.1.3 → 4.1.5

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

@@ -0,0 +1,26 @@
+---
+keywords:
+- EventCatalog entities
+- Domain model
+sidebar_label: What are entities?
+title: What are entities?
+description: What are entities? Why are they useful in EventCatalog?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+An entity is a documented business object or concept that your architecture cares about.
+
+Examples of entities include `Order`, `Customer`, `Invoice`, `Payment`, `Shipment` `Product`.
+
+Entities are useful when you want to describe the shape and relationships of your domain model, separate from the services, messages, and systems that use it. For example, in an event-driven system, `OrderCreated` might be the message, `OrderService` might be the producer, and `Order` is the entity that gives the event business meaning.
+
+Entities can be referenced from [Domains](/docs/development/guides/domains/introduction), [Systems](/docs/development/guides/systems/introduction) and [Services](/docs/development/guides/resources/services/introduction).
+
+## Next steps
+
+- [Create an entity](/docs/development/guides/resources/entities/create-entity)
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)
+- [Review the entities reference](/docs/development/guides/resources/entities/reference)

package/dist/docs/development/guides/resources/entities/02-create-entity.md

@@ -0,0 +1,162 @@
+---
+keywords:
+- EventCatalog entities
+sidebar_position: 2
+sidebar_label: Create an entity
+title: Create an entity
+description: Create an entity in 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';
+
+An entity is a documented business object or concept that your architecture cares about. You can document entity properties, and assign them to any domain, system or service in your architecture.
+
+![Example entity page in EventCatalog](./img/entity-example.png)
+
+## Creating an entity
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog entity">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/entities/create-entity.md and https://www.eventcatalog.dev/docs/development/guides/resources/entities/reference.md then help me create a new EventCatalog entity in my catalog.
+
+Ask me for the entity name, business meaning, summary, identifier field, important properties, relationships to other entities, and where the entity should live. Then create the correct entities/{'{Entity Name}'}/index.mdx, domains/{'{Domain Name}'}/entities/{'{Entity Name}'}/index.mdx, systems/{'{System Name}'}/entities/{'{Entity Name}'}/index.mdx, or services/{'{Service Name}'}/entities/{'{Entity Name}'}/index.mdx file with frontmatter and starter markdown.
+
+Use the EntityPropertiesTable component when it helps explain the properties.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you decide where the entity should live, define the properties, and create the starter documentation.
+
+### Manual Creation
+
+Most teams start by creating shared entities at the root of the catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'entities',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'order',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'customer',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+You can also keep entities inside the resource folder they clearly belong to.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Ordering',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Create the entity file
+
+Create an `index.mdx` file for the entity.
+
+```md title="/entities/order/index.mdx"
+---
+# Unique identifier for the entity. Used in URLs and resource references.
+id: order
+# Friendly display name shown in EventCatalog.
+name: Order
+# Version of this entity documentation.
+version: 1.0.0
+# Short summary shown in lists, sidebars, and previews.
+summary: Represents a customer's purchase.
+# The property that uniquely identifies this entity.
+identifier: orderId
+# Optional. Marks this entity as the aggregate root for the model.
+aggregateRoot: true
+# Teams or users that own this entity.
+owners:
+  - ordering-platform
+# Properties that describe the shape of the entity.
+properties:
+  # Unique identifier for this order.
+  - name: orderId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Unique identifier for the order.
+  # Identifier for the customer that placed the order.
+  - name: customerId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Customer that placed the order.
+    # Entity this property references.
+    references: customer
+    # Label used to describe the relationship in entity maps.
+    relationType: placedBy
+    # Identifier property on the referenced entity.
+    referencesIdentifier: customerId
+  # Current lifecycle state of the order.
+  - name: status
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Current lifecycle state of the order.
+---
+
+## Overview
+
+The Order entity represents a customer's purchase and tracks the state required to fulfil, pay for, and ship that purchase.
+
+<EntityPropertiesTable />
+```
+
+
+## Next steps
+
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)
+- [Review the entities reference](/docs/development/guides/resources/entities/reference)

package/dist/docs/development/guides/resources/entities/03-model-entity-relationships.md

@@ -0,0 +1,115 @@
+---
+keywords:
+- EventCatalog entities
+- Entity relationships
+sidebar_position: 3
+sidebar_label: Model relationships
+title: Model entity relationships
+description: Model relationships between entities in EventCatalog.
+---
+
+Entity relationships are defined on entity properties.
+
+Use relationships when one entity property identifies or points to another entity. For example, an `Order` might have a `customerId` property that references `Customer`, and an `OrderItem` might have an `orderId` property that references `Order`.
+
+```mermaid
+erDiagram
+  direction LR
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--o{ ORDER_ITEM : contains
+
+  CUSTOMER {
+    string customerId
+    string name
+  }
+
+  ORDER {
+    string orderId
+    string customerId
+    string status
+  }
+
+  ORDER_ITEM {
+    string orderItemId
+    string orderId
+    string productId
+  }
+```
+
+## Relationship fields
+
+Use these fields on an entity property:
+
+- `references`: The id of the entity being referenced.
+- `referencesIdentifier`: The property on the referenced entity that this property matches.
+- `relationType`: The relationship label, such as `belongsTo`, `hasOne`, `hasMany`, or a business-specific label.
+
+## Example relationship
+
+```md title="/entities/order/index.mdx"
+---
+# Unique identifier for the entity. Used in URLs and resource references.
+id: order
+# Friendly display name shown in EventCatalog.
+name: Order
+# Version of this entity documentation.
+version: 1.0.0
+# The property that uniquely identifies this entity.
+identifier: orderId
+# Properties that describe the shape of the entity.
+properties:
+  # Unique identifier for this order.
+  - name: orderId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+  # Identifier for the customer that placed the order.
+  - name: customerId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Customer that placed the order.
+    # Entity this property references.
+    references: customer
+    # Label used to describe the relationship in entity maps.
+    relationType: placedBy
+    # Identifier property on the referenced entity.
+    referencesIdentifier: customerId
+---
+```
+
+This tells EventCatalog that `order.customerId` references the `customer.customerId` identifier.
+
+## Relationship direction
+
+Define the relationship where the reference exists.
+
+If `Order` has a `customerId`, define the relationship on the `customerId` property in `Order`. You do not need to add the inverse relationship to `Customer` unless that relationship is useful to document explicitly.
+
+## Keep relationship labels useful
+
+Use relationship labels that help readers understand the business model.
+
+Good examples include:
+
+- `placedBy`
+- `belongsTo`
+- `contains`
+- `paysFor`
+- `shipsTo`
+
+Avoid labels that only repeat implementation detail, such as `foreignKey`.
+
+## Visual output
+
+When entities are attached to a domain or service, EventCatalog can use these relationships to generate an entity map.
+
+![Entity Map showing a relationship between OrderItem and Order](./img/simple-entity-map.png)
+
+## Next steps
+
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)

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

@@ -0,0 +1,188 @@
+---
+keywords:
+- EventCatalog entities
+- Entity resources
+sidebar_position: 4
+sidebar_label: Add entities to resources
+title: Add entities to resources
+description: Add entities to domains, systems, and services in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Adding [entities](/docs/development/guides/resources/entities/introduction) to resources helps people understand which business concepts a domain, system, or service owns, uses, or documents.
+
+In EventCatalog, entities can be connected to:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Systems](/docs/development/guides/systems/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+## Add entities using frontmatter
+
+Add entities to a resource using the `entities` array in the resource frontmatter.
+
+```md title="/domains/Ordering/index.mdx"
+---
+id: ordering
+name: Ordering
+version: 1.0.0
+# define entities that belong to this domain
+entities:
+  - id: order
+    version: 1.0.0
+  - id: customer
+---
+```
+
+You can use the same pattern for systems:
+
+```md title="/domains/Ordering/systems/order-management/index.mdx"
+---
+id: order-management
+name: Order Management
+version: 1.0.0
+# define entities that are part of this system
+entities:
+  - id: order
+  - id: shipment
+---
+```
+
+And services:
+
+```md title="/services/OrderService/index.mdx"
+---
+id: order-service
+name: Order Service
+version: 1.0.0
+# define entities this service owns, reads, writes, or exposes
+entities:
+  - id: order
+  - id: customer
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced entity.
+
+## Keep entities inside the resource folder
+
+You can also define entities inside a resource folder to keep related business model documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Ordering',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'Order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'Customer',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure makes the domain the entry point for the entities that belong to that business boundary.
+
+Entities can also live inside services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'Order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure is useful when the entity is owned by, exposed by, or tightly coupled to one service.
+
+## Keep shared entities at the root
+
+Entities can live at the root of the catalog when they are shared across multiple domains, systems, or services.
+
+<ProjectTree
+  items={[
+    {
+      name: 'entities',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Customer',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'Payment',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Use frontmatter when the entity is shared across multiple resources. Keep the entity inside a resource folder when the entity is owned by that resource and should move with it.
+
+## Show entities on resource pages
+
+When a domain, service, or system references entities, EventCatalog shows that relationship on the resource page.
+
+Domains and services can also show entity maps, which help people understand the entity relationships inside that part of your architecture.
+
+Learn more in [entity maps](/docs/development/guides/resources/entities/entity-maps) and [model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships).
+
+For the complete list of supported fields, see the [entities reference](/docs/development/guides/resources/entities/reference).

package/dist/docs/development/guides/resources/entities/05-entity-maps.md

@@ -0,0 +1,48 @@
+---
+keywords:
+- EventCatalog entities
+- Entity maps
+sidebar_position: 5
+sidebar_label: Entity maps
+title: Entity maps
+description: Visualize entity relationships in EventCatalog.
+---
+
+Entity maps help teams understand the relationships between business concepts.
+
+When entities are assigned to a domain or service, EventCatalog can create an entity map that shows:
+
+- The entities assigned to that resource.
+- Relationships between those entities.
+- Entities referenced from outside the current resource.
+- Which entities are owned by the current domain or service context.
+
+![Entity Map](./img/entity-map.png)
+
+## Open an entity map in the visualizer
+
+Domains and services have dedicated entity map routes:
+
+```txt
+/visualiser/domains/{id}/{version}/entity-map
+/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 an entity map
+
+You can also embed an entity map on a page using the `<EntityMap />` component.
+
+```mdx
+<EntityMap id="ordering" title="Ordering Entity Map" />
+```
+
+![Entity Map Component](./img/entity-map-component.png)
+
+Use embedded entity maps when you want the model to appear directly in domain, service, or custom documentation.
+
+## Next steps
+
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [EntityMap component reference](/docs/development/components/components/entitymap)