@eventcatalog/core 4.1.3 → 4.1.5

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

@@ -0,0 +1,149 @@
+---
+keywords:
+- EventCatalog flows
+sidebar_position: 4
+sidebar_label: Add flows to resources
+title: Add flows to resources
+description: Associate flows with domains, services, and systems in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Adding [flows](/docs/development/guides/resources/flows/introduction) to resources helps people understand where a business process belongs and which parts of the architecture participate in it.
+
+In EventCatalog, flows can be connected to:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Systems](/docs/development/guides/systems/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+## Add flows using frontmatter
+
+Add flows to a resource using the `flows` array in the resource frontmatter.
+
+```md title="/services/Orders/index.mdx"
+---
+id: OrdersService
+name: Orders Service
+version: 1.0.0
+# define flows this service participates in
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+  - id: PaymentFlow
+---
+```
+
+You can use the same pattern for domains:
+
+```md title="/domains/Orders/index.mdx"
+---
+id: OrdersDomain
+name: Orders
+version: 1.0.0
+# define flows that belong to this domain
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+---
+```
+
+And systems:
+
+```md title="/domains/Orders/systems/order-management/index.mdx"
+---
+id: order-management
+name: Order Management
+version: 1.0.0
+# define flows that are part of this system
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced flow.
+
+## Keep flows inside the resource folder
+
+You can also define flows inside a resource folder to keep related process documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderProcessing',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure makes the domain the entry point for the flows that belong to that business area.
+
+Flows can also live inside services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderProcessing',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure is useful when the flow is specific to one service.
+
+## Show flows on resource pages
+
+When a domain, service, or system references a flow, EventCatalog shows that relationship on the resource page and in the visualizer.
+
+Use frontmatter when the flow is shared across multiple resources. Keep the flow inside a resource folder when the flow is owned by that resource and should move with it.
+
+For the complete list of supported fields, see the [flows reference](/docs/development/guides/resources/flows/reference).

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

@@ -0,0 +1,226 @@
+---
+keywords:
+- EventCatalog flows
+- Flow frontmatter
+sidebar_position: 6
+sidebar_label: Reference
+title: Flows reference
+description: Frontmatter fields, paths, and routes for flows in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by flows.
+
+## Paths
+
+Flows can be created in any `flows` folder:
+
+```txt
+/flows/{Flow Name}/index.mdx
+/domains/{Domain Name}/flows/{Flow Name}/index.mdx
+/services/{Service Name}/flows/{Flow Name}/index.mdx
+```
+
+Versioned flows use:
+
+```txt
+/flows/{Flow Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/flows/{flow-id}/{version}` | Flow documentation page. |
+| `/visualiser/flows/{flow-id}/{version}` | Flow diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the flow. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: checkout-flow
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the flow.
+
+```md title="Example"
+---
+name: Checkout Flow
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the flow documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the flow.
+
+```md title="Example"
+---
+summary: Describes the steps from checkout start to order confirmation.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the flow.
+
+```md title="Example"
+---
+owners:
+  - checkout-platform
+---
+```
+
+### `steps` {#steps}
+
+- Type: `array`
+
+Ordered steps in the flow.
+
+```md title="Example"
+---
+steps:
+  - id: submit-order
+    title: Submit order
+    message:
+      id: SubmitOrder
+    next_step: authorize-payment
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the flow page.
+
+```md title="Example"
+---
+badges:
+  - content: Critical path
+    backgroundColor: red
+    textColor: red
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the flow.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/checkout
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the flow.
+
+```md title="Example"
+---
+diagrams:
+  - id: checkout-sequence
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the flow.
+
+```md title="Example"
+---
+attachments:
+  - title: Checkout runbook
+    url: https://runbooks.example.com/checkout
+    type: runbook
+---
+```
+
+## Step fields
+
+Each flow step supports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` or `number` | Unique step id. |
+| `title` | `string` | Step title. |
+| `summary` | `string` | Optional step summary. |
+| `message` | `object` | Message referenced by this step. |
+| `agent` | `object` | Agent referenced by this step. |
+| `service` | `object` | Service referenced by this step. |
+| `flow` | `object` | Nested flow referenced by this step. |
+| `container` | `object` | Data store referenced by this step. |
+| `dataProduct` | `object` | Data product referenced by this step. |
+| `actor` | `object` | Inline actor for this step. |
+| `custom` | `object` | Custom node for this step. |
+| `externalSystem` | `object` | External system for this step. |
+| `next_step` | `string` or `number` | Next step id. |
+| `next_steps` | `array` | Multiple next step ids. |
+
+## External services nodes {#external-services-nodes}
+
+Use `externalSystem` when a flow step points at a third-party system.
+
+```md
+---
+steps:
+  - id: payment-provider
+    title: Payment provider
+    externalSystem:
+      name: Stripe
+      summary: External payment processor.
+    next_step: complete
+---
+```
+
+## Actor nodes {#actor-nodes}
+
+Use `actor` when a flow step represents a person, role, or external participant.
+
+```md
+---
+steps:
+  - id: customer
+    title: Customer starts checkout
+    actor:
+      name: Customer
+    next_step: submit-order
+---
+```

package/dist/docs/development/guides/{flows → resources/flows}/_category_.json

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

package/dist/docs/development/guides/resources/messages/01-what-are-messages.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: What are messages?
+title: What are messages?
+description: Understand events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog supports different types of messages ([commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) and [queries](/docs/development/guides/resources/messages/message-types/queries)).
+
+- **Commands** - represent intent, commands can be rejected in distributed systems.
+- **Events** - represents an immutable fact.
+- **Queries** - represent requests for information.
+
+
+### Linking messages to services, domains and channels
+
+- Messages can be sent (producer) or received (consumer) by [services](/docs/development/guides/resources/services/introduction), [domains](/docs/development/guides/domains/add-resources-to-domains/add-messages-to-domains) or be totally independent.
+- You can also route messages through one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g queue, broker, bus).
+
+### Where do messages live?
+
+Messages can live anywhere in your catalog, at the service level or domain level.
+
+**Example of a message living at the service level**
+
+Here we have the `OrderPlaced` message living at the service level.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+**Example of a message living at the domain level**
+
+Here we have the `OrderPlaced` message living at the domain level.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::tip You can reference messages from anywhere in your catalog
+It does not matter where you store your messages, you can reference them from anywhere in your catalog.
+Your domains and services will reference them by their `id` and optionally the `version`. EventCatalog will resolve the message.
+:::

package/dist/docs/development/guides/{messages/events/01-introduction.md → resources/messages/02-message-types/01-events.md}

@@ -3,17 +3,13 @@ sidebar_position: 1
 keywords:
 - EventCatalog services
 - Events
-sidebar_label: What are events?
-title: Understanding events
+sidebar_label: Events
+title: Events
 description: What are events? Why are they useful for event-driven architectures?
 ---
 
 Events are a type of message that represent immutable facts.
 
-In EventCatalog [Services](/docs/development/guides/services/introduction) may send (produce) or receive (consume) events in your architecture.
-
-### Example of an event
-
 An example of an event would be `OrderPlaced` event.
 
 - This event is a fact that an order has been placed.
@@ -22,4 +18,4 @@ An example of an event would be `OrderPlaced` event.
 ### Events in EventCatalog
 
 - Events in EventCatalog are orange (following [EventStorming conventions](https://www.eventstorming.com/))
-- Events live in the `/events` folder or inside a [service](/docs/development/guides/services/introduction) folder.
+- Events live in the `/events` folder.

package/dist/docs/development/guides/{messages/commands/01-introduction.md → resources/messages/02-message-types/02-commands.md}

@@ -3,16 +3,14 @@ sidebar_position: 1
 keywords:
 - EventCatalog services
 - Commands
-sidebar_label: What are commands?
-title: Understanding commands
+sidebar_label: Commands
+title: Commands
 description: What are commands? Why are they useful for event-driven architectures?
 ---
 
 Commands are messages that represent intent, commands can be rejected in distributed systems.
 
-In EventCatalog [Services](/docs/development/guides/services/introduction) may invoke (send) or accept (receive) commands in your architecture.
-
-### Example of a command
+In EventCatalog [Services](/docs/development/guides/resources/services/introduction) may invoke (send) or accept (receive) commands in your architecture.
 
 An example of a command would be `PlaceOrder` message over HTTP.
 
@@ -21,6 +19,5 @@ An example of a command would be `PlaceOrder` message over HTTP.
 
 ### Commands in EventCatalog
 
-- Commands in EventCatalog can be **accepted** by services or **invoked** by services.
 - Commands in EventCatalog are blue (following [EventStorming conventions](https://www.eventstorming.com/))
-- Commands live in the `/commands` folder.
+- Commands live in the `/commands` folder.

package/dist/docs/development/guides/resources/messages/02-message-types/03-queries.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: Queries
+title: Queries
+description: What are queries? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Queries are a type of message that represent requests for information (e.g a GET request)
+
+In EventCatalog [Services](/docs/development/guides/resources/services/introduction) may query (send) or accept (receive) queries in your architecture.
+
+### Queries in EventCatalog
+
+- Queries in EventCatalog are green
+- Queries live in the `/queries` folder.

package/dist/docs/development/guides/resources/messages/02-message-types/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Message types",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/message-types",
+    "description": "Understand events, commands, and queries in EventCatalog."
+  }
+}