@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/development/guides/flows/03-flow-nodes.md

@@ -0,0 +1,273 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog flows
+sidebar_label: Flow nodes
+title: Flow nodes types
+description: Flow nodes 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.
+
+With flow nodes you can reference your services, events, commands and queries, external systems, users (actors) or even create your own custom nodes.
+
+EventCatalog (> 2.34.2) you can also reference flows as a node type.
+
+## Common step properties
+
+Every flow step (regardless of node type) supports these properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string \| number` | **Yes** | Unique identifier for the step |
+| `title` | `string` | **Yes** | The label displayed on the node in the flow diagram |
+| `summary` | `string` | No | A short description shown in the node sidebar |
+| `type` | `"node" \| "message" \| "user" \| "actor"` | No | Hint for how the node should be rendered |
+| `next_step` | [Step reference](#connecting-steps) | No | The next step in the flow (cannot be used with `next_steps`) |
+| `next_steps` | [Step reference](#connecting-steps)[] | No | Multiple next steps for branching (cannot be used with `next_step`) |
+
+:::tip Type exclusivity rule
+Each step can only use **one** node type property. You cannot combine `message`, `service`, `flow`, `actor`, `custom`, or `externalSystem` on the same step.
+:::
+
+## Connecting steps {#connecting-steps}
+
+Use `next_step` or `next_steps` (not both) to connect steps together.
+
+A step reference can be:
+- A **string or number** matching another step's `id` (e.g. `next_step: "step-2"`)
+- An **object** with `id` and an optional `label` for the edge
+
+```yml
+# Simple reference
+next_step: "step-2"
+
+# Reference with edge label
+next_step:
+  id: "step-2"
+  label: "on success"
+
+# Multiple next steps (branching)
+next_steps:
+  - id: "step-success"
+    label: "on success"
+  - id: "step-failure"
+    label: "on failure"
+```
+
+## Flow node types
+
+- [default](#default) — A blank node type with just a title in your flow
+- [actor](#actor) — Represents a person in your flow diagram
+- [externalSystem](#externalsystem) — Represents an external system in your flow diagram
+- [message](#message) — Represents an event, command or query resource in EventCatalog
+- [service](#service) — Represents a service resource in EventCatalog
+- [flow](#flow) — Represents a flow in EventCatalog (added in EventCatalog 2.34.2)
+- [custom](#custom) — A custom node type with configurable title, summary, icon, properties and more
+
+
+### default node type {#default}
+
+A blank node type with just a title in your flow. No additional properties are needed beyond the [common step properties](#common-step-properties).
+
+```yml
+steps:
+  - id: "step-1"
+    title: "This value will be shown in the node on the flow diagram"
+```
+
+---
+
+### actor
+
+Actor represents a person in your flow diagram.
+
+#### Actor properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | **Yes** | The name of the actor |
+| `summary` | `string` | No | A short description of the actor (added in EventCatalog 2.55.6) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Actor"
+    actor:
+      name: "Dave"
+      summary: "This is a summary of the actor"
+```
+
+---
+
+### externalSystem
+
+Represents an external system in your flow diagram.
+
+#### External system properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | **Yes** | The name of the external system |
+| `summary` | `string` | No | A short description of the external system |
+| `url` | `string` (valid URL) | No | A link to the external system |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a externalSystem"
+    externalSystem:
+      name: "Google"
+      summary: "Search engine"
+      url: "https://google.com"
+```
+
+---
+
+### message
+
+Represents and refers to an event, command or query resource in EventCatalog.
+
+#### Message properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the event, command or query in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Event"
+    message:
+      id: "order-placed"
+      version: "0.0.1"
+```
+
+---
+
+### service
+
+Represents and refers to a service resource in EventCatalog.
+
+#### Service properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the service in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Service"
+    service:
+      id: "order-service"
+      version: "0.0.1"
+```
+
+---
+
+### flow
+
+<AddedIn version="2.34.2" />
+
+Represents and refers to a flow resource in EventCatalog. Useful for reusing flows in your flow diagrams.
+
+#### Flow properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the flow in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Flow"
+    flow:
+      id: "order-flow"
+      version: "0.0.1"
+```
+
+#### Expand inline
+
+<AddedIn version="3.29.0" />
+
+Click a flow node in the visualiser to expand the referenced flow's steps inline. Use the Collapse button in the expanded node's header to restore the single-node view. The graph recentres automatically on both expand and collapse, and expanded steps join the parent flow's step walkthrough navigation.
+
+---
+
+### custom
+
+<AddedIn version="2.30.6" />
+
+The custom node allows you to define any custom node you want in your flow diagram.
+
+Use cases could include:
+
+- A custom node that represents a scheduled job
+- A custom node that represents a batch job
+- A custom node that represents a decision
+- A custom node that represents a process
+- A custom node that represents an aggregate
+
+**Custom nodes can be anything you want.**
+
+You can view a UI example of a custom nodes [here](https://demo.eventcatalog.dev/visualiser/flows/SubscriptionRenewed/1.0.0).
+
+#### Custom node properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `title` | `string` | **Yes** | The title shown on the node |
+| `icon` | `string` | No | Icon shown on the node (see [Heroicons](https://heroicons.com/) for the list of icons) |
+| `type` | `string` | No | A type label shown on the sidebar of the node (e.g. "Scheduler", "Database") |
+| `summary` | `string` | No | A short description of the node |
+| `url` | `string` (valid URL) | No | A link associated with the custom node |
+| `color` | `string` | No | The color of the node (see [Tailwind colors](https://tailwindcss.com/docs/colors)) |
+| `properties` | `Record<string, string \| number>` | No | Key-value pairs shown in the node. URL values are rendered as links |
+| `height` | `number` | No | The height of the node (be careful going too high, the diagram does not calculate the graph based on the height of nodes) |
+| `menu` | `{ label: string, url?: string }[]` | No | Right-click context menu items |
+
+**UI Example**
+
+<img src="/img/custom-flow.png" alt="Custom Node" style={{width: "50%"}} />
+
+---
+
+**MDX Example**
+
+This example shows a custom node that represents a scheduler.
+
+```yml
+steps:
+  - id: "renewal_timer_triggered"
+    title: "Renewal Period Reached"
+    custom:
+      title: "Renewal Timer"
+      color: "orange"
+      icon: "ClockIcon"
+      type: "Scheduler"
+      summary: "Automated timer triggers the subscription renewal process"
+      height: 8
+      properties:
+        subscription_id: "sub_12345678"
+        renewal_type: "Automatic"
+        billing_cycle: "Monthly"
+        next_billing_date: "2024-08-01"
+      menu:
+        - label: "View scheduler configuration"
+          url: "https://docs.example.com/scheduler"
+        - label: "Subscription timing documentation"
+          url: "https://docs.example.com/subscription-timing"
+    next_step:
+      id: "check_subscription_status"
+      label: "Verify subscription status"
+```
+
+You can find a full example on GitHub [here](https://raw.githubusercontent.com/event-catalog/eventcatalog/refs/heads/main/examples/default/domains/Subscriptions/flows/SubscriptionRenewed/index.mdx).

package/dist/docs/development/guides/flows/04-adding-flows-to-services.md

@@ -0,0 +1,42 @@
+---
+keywords:
+- EventCatalog flows
+sidebar_label: Adding flows to services
+title: Adding flows to services
+description: Associate flows with services in EventCatalog
+---
+
+Adding [flows](/docs/development/guides/flows/introduction) to your services helps document which business processes or workflows involve a particular service.
+
+When adding flows to your service EventCatalog will:
+
+- Show the flows in the service sidebar
+- Create clear relationships between services and the processes they participate in
+
+You can also place flow files directly inside a service directory. EventCatalog discovers any `index.mdx` inside a `flows` folder at any depth, so `/services/PaymentService/flows/ProcessPayment/index.mdx` is a valid location.
+
+## Add flows using frontmatter
+
+To add flows to a service you need to add them to the `flows` array within your service frontmatter API.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrdersService
+... # other service frontmatter
+flows:
+    # id of the flow you want to add
+    - id: OrderProcessing
+    # (optional) The version of the flow you want to add.
+      version: 1.0.0
+
+    # Note: version is optional. If no version is given the latest version of the flow will be used.
+    - id: PaymentFlow
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `flows` frontmatter in your service tells EventCatalog that these documented flows involve this service.
+
+In the example above we can see that the flows `OrderProcessing` and `PaymentFlow` involve the `OrdersService`.

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

@@ -0,0 +1,43 @@
+---
+keywords:
+- EventCatalog flows
+sidebar_label: Adding flows to domains
+title: Adding flows to domains
+description: Associate flows with domains in EventCatalog
+---
+
+Adding [flows](/docs/development/guides/flows/introduction) to your domains helps document which business processes or workflows belong to a particular domain.
+
+When adding flows to your domain EventCatalog will:
+
+- Show the flows in the domain sidebar
+- Create clear relationships between domains and the processes they contain
+
+You can also place flow files directly inside a domain directory. EventCatalog discovers any `index.mdx` inside a `flows` folder at any depth, so `/domains/Orders/flows/ProcessOrder/index.mdx` is a valid location.
+
+## Add flows using frontmatter
+
+To add flows to a domain you need to add them to the `flows` array within your domain frontmatter API.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: OrdersDomain
+... # other domain frontmatter
+flows:
+    # id of the flow you want to add
+    - id: OrderProcessing
+    # (optional) The version of the flow you want to add.
+      version: 1.0.0
+
+    # Note: version is optional. If no version is given the latest version of the flow will be used.
+    - id: PaymentFlow
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `flows` frontmatter in your domain tells EventCatalog that these documented flows belong to this domain.
+
+In the example above we can see that the flows `OrderProcessing` and `PaymentFlow` belong to the `OrdersDomain`.
+

package/dist/docs/development/guides/flows/06-versioning.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 6
+keywords:
+- versioning
+- services
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version flows
+---
+
+
+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.
+
+## How to version a flow
+
+1. Create a `/versioned` directory inside the `/flows` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/flows/ProcessingPayments/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/flows/ProcessingPayments/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 `/flows/ProcessingPayments/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/flows/ProcessingPayments/1.0.2 would load the 1.0.2 version of this flow).

package/dist/docs/development/guides/flows/07-create-flow-with-ai.md

@@ -0,0 +1,171 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog flows
+- AI flow wizard
+- flow documentation
+- AI skills
+sidebar_label: Creating a flow (with AI)
+title: Creating a flow (with AI)
+description: Interactively document business flows using an AI agent skill.
+---
+
+The [`flow-wizard` skill](/docs/development/ask-your-architecture/skills/introduction#available-skills) guides your AI agent through documenting a business flow step by step. Instead of writing the YAML frontmatter by hand, you have a conversation with your agent describing what happens in each stage and the skill builds the flow for you.
+
+The skill also cross-references your existing catalog resources (services, events, commands, queries) and links them into the flow automatically when it finds a match.
+
+## Prerequisites
+
+- An AI coding agent that supports the skills format (e.g. [Claude Code](https://claude.ai/code))
+- The `flow-wizard` skill installed in your project (see [installation](/docs/development/ask-your-architecture/skills/installation))
+- Optionally, an EventCatalog MCP server connection so the agent can query your catalog directly
+
+## Install the skill
+
+```bash
+# Install all EventCatalog skills
+npx skills add event-catalog/skills
+
+# Install only the flow-wizard skill
+npx skills add event-catalog/skills --skill flow-wizard
+```
+
+This copies the skill into `.claude/skills/flow-wizard/` where your agent can access it.
+
+## Start a session
+
+Open your AI agent and ask it to document a flow using natural language. The skill activates on phrases like:
+
+- "document a flow"
+- "map a business process"
+- "create a flow diagram"
+- "walk through a process"
+- "document an end-to-end flow"
+- "map out how something works in my architecture"
+
+**Example prompt:**
+
+> "Use the flow-wizard skill to help me document our checkout flow."
+
+## How a session works
+
+The wizard runs through a structured conversation. You describe your flow in plain language -- the agent handles the formatting.
+
+### Locate your catalog
+
+The agent first asks whether you have an EventCatalog project and where it lives. It scans your `services/`, `events/`, `commands/`, `queries/`, `domains/`, and `flows/` directories to build an inventory of existing resources.
+
+If you have the EventCatalog MCP server connected, the agent uses `getResources` to query the catalog directly. If you don't have a catalog yet, the agent documents steps as plain descriptions and you can add resource links later.
+
+### Describe the flow
+
+You describe the end-to-end process in your own words:
+
+> "A user places an order, payment is processed, inventory is reserved, and a confirmation email is sent."
+
+The agent breaks this into sections and presents them back for your confirmation before continuing.
+
+### Walk through each section
+
+The agent takes you through each section one at a time, asking what happens, who or what is involved, and what comes next.
+
+For each step it asks about, the agent:
+
+1. Determines the step type -- `actor`, `service`, `message`, or `externalSystem`
+2. Searches your catalog for a matching resource
+3. Presents any matches and asks you to confirm before linking them
+
+If a resource exists in your catalog, the agent uses its exact `id` and `version`. If nothing matches, it creates a placeholder and notes that you can document it fully later.
+
+### Handle branching
+
+When you describe a decision point ("if payment succeeds we continue, otherwise we notify the user"), the agent asks you to confirm the paths and documents them as `next_steps` branches.
+
+```yaml
+next_steps:
+  - id: "reserve_inventory"
+    label: "Payment succeeded"
+  - id: "notify_failure"
+    label: "Payment failed"
+```
+
+### Review and confirm
+
+Before writing any file, the agent shows a complete summary of every step, which resources were matched from your catalog, and which are new placeholders. You can request changes before the file is generated.
+
+### Generated output
+
+The agent writes an `index.mdx` file to your catalog. It asks where to save it if the location is ambiguous -- either `flows/{FlowName}/index.mdx` or `domains/{Domain}/flows/{FlowName}/index.mdx`.
+
+_PLACE_HOLDER_IMAGE_
+
+A generated flow might look like this:
+
+```md title="flows/CheckoutFlow/index.mdx (example)"
+---
+id: "CheckoutFlow"
+name: "Checkout Flow"
+version: "0.0.1"
+summary: "End-to-end flow from cart submission through payment to order confirmation"
+steps:
+  - id: "customer_submits_order"
+    title: "Customer Submits Order"
+    actor:
+      name: "Customer"
+    next_step:
+      id: "place_order_command"
+      label: "Submit order"
+
+  - id: "place_order_command"
+    title: "Place Order"
+    message:
+      id: "PlaceOrder"
+      version: "1.0.0"
+    next_step:
+      id: "orders_service"
+      label: "Send to Orders Service"
+
+  - id: "orders_service"
+    title: "Orders Service"
+    service:
+      id: "OrdersService"
+      version: "2.1.0"
+    next_steps:
+      - id: "payment_gateway"
+        label: "Process payment"
+      - id: "order_rejected"
+        label: "Reject order"
+
+  - id: "payment_gateway"
+    title: "Stripe"
+    externalSystem:
+      name: "Stripe"
+      summary: "Third-party payment processor"
+      url: "https://stripe.com"
+    next_step:
+      id: "order_confirmed"
+      label: "Payment complete"
+
+  - id: "order_confirmed"
+    title: "Order Confirmed"
+    message:
+      id: "OrderConfirmed"
+      version: "1.0.0"
+
+  - id: "order_rejected"
+    title: "Order Rejected"
+    message:
+      id: "OrderRejected"
+      version: "1.0.0"
+---
+
+<NodeGraph />
+```
+
+Once saved, the flow appears in your EventCatalog at `http://localhost:3000/visualiser/flows/CheckoutFlow/0.0.1`.
+
+## Next steps
+
+- Resources the agent could not match are noted in the session summary. Use the `catalog-documentation-creator` skill to document those resources.
+- See [flow nodes](/docs/development/guides/flows/flow-nodes) for the full list of step types you can use to extend the generated flow.
+- See [adding flows to domains](/docs/development/guides/flows/adding-flows-to-domains) if you want to move the flow under a domain.

package/dist/docs/development/guides/flows/_category_.json

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

package/dist/docs/development/guides/messages/01-overview.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: Overview
+title: Overview
+description: What are messags in EventCatalog?
+---
+
+EventCatalog supports different types of messages ([commands](/docs/development/guides/messages/commands/introduction), [events](/docs/development/guides/messages/events/introduction) and [queries](/docs/development/guides/messages/queries/introduction)).
+
+- **Commands**
+    - Commands are messages that represent intent, commands can be rejected in distributed systems.
+- **Events**
+    - Events are a type of message that represent immutable facts.
+- **Queries**
+    - Queries are a type of message that represent requests for information.
+
+
+### Linking messages to services, domains and channels
+
+- Messages can be sent (producer) or received (consumer) by [services](/docs/development/guides/services/introduction), [domains](/docs/development/guides/domains/creating-domains/adding-messages-to-domains) or be totally independent.
+- You can also route messages through one or more [channels](/docs/development/guides/channels/adding-messages-to-services).
+
+### 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.
+
+```md
+services/
+  Orders/
+    events/
+      OrderPlaced/
+        index.mdx
+```
+
+**Example of a message living at the domain level**
+
+Here we have the `OrderPlaced` message living at the domain level.
+
+```md
+domains/
+  Orders/
+    events/
+      OrderPlaced/
+        index.mdx
+```
+
+:::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/_category_.json

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

package/dist/docs/development/guides/messages/commands/01-introduction.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Commands
+sidebar_label: What are commands?
+title: Understanding 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
+
+An example of a command would be `PlaceOrder` message over HTTP.
+
+- This message is used to place an order in a system
+- Commands can be rejected, the `PlaceOrder` may be rejected by the service that processes it.
+
+### 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.