@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/resources/entities/06-reference.md

@@ -0,0 +1,273 @@
+---
+keywords:
+- EventCatalog entities
+- Entity frontmatter
+sidebar_position: 6
+sidebar_label: Reference
+title: Entities reference
+description: Frontmatter fields, paths, and routes for entities in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by entities.
+
+## Paths
+
+Entities can be created at the root of your catalog:
+
+```txt
+/entities/{Entity Name}/index.mdx
+```
+
+Entities can also be created inside domains, systems, or services:
+
+```txt
+/domains/{Domain Name}/entities/{Entity Name}/index.mdx
+/systems/{System Name}/entities/{Entity Name}/index.mdx
+/domains/{Domain Name}/systems/{System Name}/entities/{Entity Name}/index.mdx
+/services/{Service Name}/entities/{Entity Name}/index.mdx
+```
+
+Versioned entities use:
+
+```txt
+/entities/{Entity Name}/versioned/{version}/index.mdx
+```
+
+Nested entities use the same `versioned/{version}/index.mdx` pattern inside their entity folder.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/entities/{entity-id}/{version}` | Entity documentation page. |
+| `/visualiser/entities/{entity-id}/{version}` | Entity resource diagram. |
+| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity map for entities assigned to a domain. |
+| `/visualiser/services/{service-id}/{version}/entity-map` | Entity map for entities assigned to a service. |
+
+## Frontmatter example
+
+```md
+---
+# 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 order identifier.
+  # 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
+    # Allowed values for the property.
+    enum:
+      - pending
+      - confirmed
+      - cancelled
+---
+```
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the entity. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: order
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the entity.
+
+```md title="Example"
+---
+name: Order
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the entity documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the entity represents.
+
+```md title="Example"
+---
+summary: Represents a customer's purchase.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the entity.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `aggregateRoot` {#aggregateRoot}
+
+- Type: `boolean`
+
+Marks the entity as an aggregate root.
+
+```md title="Example"
+---
+aggregateRoot: true
+---
+```
+
+### `identifier` {#identifier}
+
+- Type: `string`
+
+The property that uniquely identifies the entity.
+
+```md title="Example"
+---
+identifier: orderId
+---
+```
+
+### `properties` {#properties}
+
+- Type: `array`
+
+Properties that describe the shape of the entity.
+
+```md title="Example"
+---
+properties:
+  - name: orderId
+    type: string
+    required: true
+    description: Unique order identifier.
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the entity page.
+
+```md title="Example"
+---
+badges:
+  - content: Aggregate root
+    backgroundColor: blue
+    textColor: blue
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the entity.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/orders
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the entity.
+
+```md title="Example"
+---
+attachments:
+  - title: Order model runbook
+    url: https://runbooks.example.com/orders
+    type: runbook
+---
+```
+
+## Property fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Property name. |
+| `type` | `string` | Property type, such as `string`, `UUID`, `datetime`, or another entity name. |
+| `required` | `boolean` | Whether the property is required. |
+| `description` | `string` | Description of the property. |
+| `references` | `string` | Entity id referenced by this property. |
+| `referencesIdentifier` | `string` | Identifier property on the referenced entity. |
+| `relationType` | `string` | Relationship label shown in entity maps. |
+| `enum` | `array` | Allowed string values. |
+| `items` | `object` | Item type for array properties. |
+
+## EntityPropertiesTable component
+
+Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity properties as a table.
+
+```mdx
+<EntityPropertiesTable />
+```
+
+This is useful when you want the documentation page to show the same properties defined in frontmatter.

package/dist/docs/development/guides/{domains/05-entities → resources/entities}/_category_.json

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

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

@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog flows
+- Flows
+sidebar_label: What are flows?
+title: Understanding flows
+description: What are flows? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Flows are a way to document business workflows in your organization. Flows help teams understand end-to-end flows across your organization and architecture.
+
+An example of a flow could be user purchasing a product in an e-commerce store. They start by logging into a service, getting onboarded and purchasing something from a business. Across this journey may applications, databases, interactions are happening. Flows let you capture these.
+
+You can reuse your documented resources (e.g services, messages, data stores, data products) in your flows.
+
+![Example](../../img/flows/flow-example.png)
+
+<!-- [You can see a payment flow example here](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0). -->
+
+
+<!-- 
+### Further reading
+- [Event-driven architecture and domain-driven design](https://eda-visuals.boyney.io/visuals/eda-and-ddd)
+- [Domain, Subdomain, Bounded Context: Problem/Solution Space in DDD: Clearly Defined](https://medium.com/nick-tune-tech-strategy-blog/domains-subdomain-problem-solution-space-in-ddd-clearly-defined-e0b49c7b586c)
+- [Building Blocks of DDD](https://redis.io/glossary/domain-driven-design-ddd/) -->

package/dist/docs/development/guides/resources/flows/02-create-flow.md

@@ -0,0 +1,304 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog flows
+sidebar_label: Create a flow
+title: Create a flow
+description: Creating and managing flows 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';
+
+<AddedIn version="2.5.0" />
+
+Flows document business processes, user journeys, and architecture workflows across your catalog.
+
+Users can step through flows step by step, and your flows can reference any resource in EventCatalog or define custom nodes.
+
+![Example flow page in EventCatalog](../../img/flows/flow-example.png)
+
+## Creating a flow
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog flow">
+Read https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/flow-wizard/SKILL.md and follow that wizard.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you identify the steps, connect them, choose where the flow should live, and create the first version of the flow documentation.
+
+:::tip EventCatalog Skills
+You can install the EventCatalog Skills (https://github.com/event-catalog/skills/tree/main/skills/flow-wizard) and use the [flow-wizard](https://github.com/event-catalog/skills/tree/main/skills/flow-wizard) skill to help you document your business workflow. Use natural language and your LLM will do the rest.
+:::
+
+### Manual Creation
+
+Flows live in a `flows` folder. EventCatalog discovers any `index.mdx` file inside a `flows` directory, regardless of where that directory lives in your catalog.
+
+You can place flows:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'flows',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'cancel-subscription',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Subscriptions',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cancel-subscription',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'SubscriptionService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cancel-subscription',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+## Create the flow file
+
+Create an `index.mdx` file for the flow.
+
+_Here is an example of what a flow file may look like._
+
+```md title="/flows/CancelSubscription/index.mdx (example)"
+---
+id: "CancelSubscription"
+name: "User Cancels Subscription"
+version: "0.0.1"
+summary: "Flow for when a user has cancelled a subscription"
+steps:
+  - id: "cancel_subscription_initiated"
+    title: "Cancels Subscription"
+    summary: "User cancels their subscription"
+    # define the actor for, in this case it's a user.
+    actor:
+      name: "User"
+    # What happens next? Define the next step  
+    next_step: 
+      id: "cancel_subscription_request"
+      label: "Initiate subscription cancellation"
+
+  - id: "cancel_subscription_request"
+    title: "Cancel Subscription"
+    # This step is a message, include the message and version
+    message:
+      id: "CancelSubscription"
+      version: "0.0.1"
+    next_step: 
+      id: "subscription_service"
+      label: "Proceed to subscription service"
+
+  - id: "stripe_integration"
+    title: "Stripe"
+    # This is an external system (e.g Stripe)
+    externalSystem:
+      name: "Stripe"
+      summary: "3rd party payment system"
+      url: "https://stripe.com/"
+    next_step: 
+      id: "subscription_service"
+      label: "Return to subscription service"
+
+  - id: "subscription_service"
+    title: "Subscription Service"
+    # This node is a service, include that.
+    service:
+      id: "SubscriptionService"
+      version: "0.0.1"
+    # Define multiple steps
+    next_steps:
+      - id: "stripe_integration"
+        label: "Cancel subscription via Stripe"
+      - id: "subscription_cancelled"
+        label: "Successful cancellation"
+      - id: "subscription_rejected"
+        label: "Failed cancellation"
+
+  - id: "subscription_cancelled"
+    title: "Subscription has been Cancelled"
+    message:
+      id: "UserSubscriptionCancelled"
+      version: "0.0.1"
+    next_step:
+      id: "notification_service"
+      label: "Email customer"
+
+  - id: "subscription_rejected"
+    title: "Subscription cancellation has been rejected"
+
+  - id: "notification_service"
+    title: "Notifications Service"
+    service:
+      id: "NotificationService"
+      version: "0.0.2"
+
+---
+
+This flow documents what happens when a User Cancels Subscription in our system. 
+
+<NodeGraph />
+
+<!-- Add any markdown you want, the workflow will also render in its own page /docs/flows/{Flow}/{version} -->
+
+```
+
+Once this file is added, the flow will automatically appear in EventCatalog.
+
+## Add subflows / reuseable flows
+
+You can reference a flow from another flow. This lets you reuse flows in your flow diagrams, useful if you have complex flows that reuse information from another flow.
+
+You can also group related flows by placing them in subdirectories inside any `flows` folder. EventCatalog discovers them regardless of nesting depth.
+
+<ProjectTree
+  items={[
+    {
+      name: 'flows',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Payments',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'ProcessPayment',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+            {
+              name: 'RefundPayment',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+          ],
+        },
+        {
+          name: 'Subscriptions',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'CancelSubscription',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The flow `id` in your frontmatter is what EventCatalog uses for routing and references. The directory structure is purely for organization.
+
+To reference a flow from another flow, use the `flow` node type.
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Event"
+    flow:
+      id: "order-flow"
+      version: 0.0.1
+```
+
+This will render the `order-flow` within the described flow.
+Right clicking on the `order-flow` node will let you navigate to the referenced flow.
+
+### Expand sub-flows inline
+
+Click any sub-flow node in the visualiser to expand its steps inline inside the parent flow diagram. Click the Collapse button in the expanded node's header to restore the single-node view.
+
+![Expanded sub-flow showing inline steps inside a parent flow diagram](/img/docs/subflow-assets/subflow-expanded.png)
+
+Expanded steps participate in the step-by-step walkthrough, so you can navigate through them using the next/previous controls without leaving the parent flow. Nested sub-flows (a sub-flow that itself references another flow) also expand correctly.
+
+### Tips for flow content
+
+It's entirely up to you what you want to add to your flows markdown content but here are a few things you might want to consider.
+
+- Context of the flow. What is it? Why does it exist?
+- Examples of how to trigger the flow?
+- Any edit/contributing guidelines?
+
+[See a flow example](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0).

package/dist/docs/development/guides/{flows/03-flow-nodes.md → resources/flows/03-model-flow-steps.md}

@@ -2,18 +2,18 @@
 sidebar_position: 3
 keywords:
 - EventCatalog flows
-sidebar_label: Flow nodes
-title: Flow nodes types
-description: Flow nodes types within EventCatalog.
+sidebar_label: Model flow steps
+title: Model flow steps
+description: Flow step types within EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
 <!-- <AddedIn version="2.5.0" /> -->
 
-Flow nodes are the building blocks of flows. They are used to represent the different steps in a flow.
+Nodes are the building blocks of flows. They are used to represent the different steps in a flow.
 
-With flow nodes you can reference your services, events, commands and queries, external systems, users (actors), data stores (containers), data products, or create your own custom nodes.
+With flow nodes you can reference your services, events, commands and queries, external services, users (actors), data stores, data products, or create your own custom nodes.
 
 ## Common step properties
 
@@ -177,7 +177,7 @@ steps:
 
 <AddedIn version="3.41.0" />
 
-Represents and refers to an [agent](/docs/development/guides/agents/introduction) resource in EventCatalog. Agents render as purple/violet nodes in the visualiser so they are easy to distinguish from services. When a flow references an agent, the agent's page shows a back-link to the flow.
+Represents and refers to an [agent](/docs/development/guides/resources/agents/introduction) resource in EventCatalog. Agents render as purple/violet nodes in the visualiser so they are easy to distinguish from services. When a flow references an agent, the agent's page shows a back-link to the flow.
 
 #### Agent properties