@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/domains/05-entities/04-domain-entity-map.md

@@ -0,0 +1,134 @@
+---
+keywords:
+- EventCatalog Entity Map
+- Domain-Driven Design
+- Entity Visualization
+- Domain Entities
+- Service Entities
+sidebar_label: Visualizing entities
+title: Entity Maps
+description: Visualize and explore entity relationships within your domains and services using EventCatalog's Entity Map feature.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.49.0" />
+
+The Entity Map is a visualization feature in EventCatalog that helps you understand the relationships between entities within your domains and services. Since entities represent the core building blocks of your domain model, visualizing their connections provides valuable insights into your architecture.
+
+## What is the Entity Map?
+
+The Entity Map is a visual representation that shows how entities are connected within a domain or service. It displays:
+
+- **Entities**: The core objects with unique identity in your domain
+- **Relationships**: How entities connect to each other
+- **Context**: Which domain or service each entity belongs to
+- **Hierarchical Structure**: How entities are organized
+
+This visualization helps teams understand the domain model at a glance and identify potential architectural improvements.
+
+## Entity Map Views
+
+EventCatalog provides two main ways to view and interact with Entity Maps:
+
+- [Entity Map in the Visualizer](#entity-map-in-the-visualizer)
+- [Embed Entity Map as Component](#embed-entity-map-as-component)
+
+### Entity Map in the Visualizer
+
+The **Entity Map Visualizer** is a dedicated page that provides a comprehensive view of all entities within a domain or service.
+
+- Domains: `/visualiser/domains/{id}/{version}/entity-map` ([see demo](https://demo.eventcatalog.dev/visualiser/domains/Orders/0.0.3/entity-map))
+- Services: `/visualiser/services/{id}/{version}/entity-map`
+
+When a domain or service has entities assigned, an **Entity Map** link appears automatically in the sidebar under the visualizer section.
+
+Entities that are referenced in another domain will be shown as **yellow**.
+
+![Entity Map](./img/entity-map.png)
+
+ This full-screen visualization offers:
+
+- **Interactive Navigation**: Click and drag to explore the entity relationships
+- **Zoom Controls**: Zoom in for detailed views or zoom out for the big picture
+- **Entity Details**: Hover over an entity property to see its description
+- **Filter Options**: Focus on specific types of entities or relationships
+
+### Embed Entity Map as Component
+
+You can embed the Entity Map of a domain on any page in your catalog using the `<EntityMap id="domain-name" />` component ([see demo](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3#entity-map)).
+
+![Entity Map Component](./img/entity-map-component.png)
+
+This compact version provides:
+
+- **Contextual View**: Shows entities relevant to the current domain or service
+- **Embedded Integration**: Seamlessly integrates with your documentation
+- **Quick Reference**: Provides a visual summary without leaving the current page
+- **Clickable Entities**: Navigate to detailed entity documentation
+
+## How to create references between entities
+
+To define relationships between entities in EventCatalog, follow these steps:
+
+### 1. Create Your Entities
+
+Start by creating your entities in your EventCatalog.  
+
+Refer to the [entity creation guide](/docs/development/guides/domains/entities/adding-entities) for detailed instructions, or you can read the [Entity API documentation](/docs/api/entity-api) for more details.
+
+### 2. Use Reference Fields in Properties
+
+Once your entities are created, you can use optional fields in your entity properties to define relationships between them.
+
+The supported fields are:
+
+- `references`: The name of the entity you want to reference (e.g. `Order`)
+- `relationType`: The type of relationship (e.g. `hasOne`, `hasMany`, `belongsTo`)
+- `referencesIdentifier`: The property name in the referenced entity used to establish the relationship (e.g. `orderId`)
+
+_More information on the reference fields can be found in the [Entity API documentation](/docs/api/entity-api)._
+
+### Example: `OrderItem` referencing `Order`
+
+Let’s say you have an `OrderItem` entity that needs to reference an `Order` entity:
+
+- The `orderId` property in `OrderItem` is used to reference the `Order`.
+- Set `references` to `Order` to indicate which entity is being referenced.
+- Set `relationType` to `hasOne` to represent that each `OrderItem` is linked to one `Order`.
+- Set `referencesIdentifier` to `orderId` to specify the matching field in the `Order` entity.
+
+```yaml
+---
+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
+---
+```
+
+### Visual Output
+
+This configuration generates an entity map that visually shows the relationship between `OrderItem` and `Order`.
+
+![Entity Map](./img/simple-entity-map.png)
+
+### Embed in Backstage
+
+If you are using Backstage, you can embed the entity map in your Backstage entity page using the `<EventCatalogEntityEntityMapCard />` component.
+
+You can read more about how to embed the entity map in Backstage in the [Backstage plugin documentation](/docs/plugins/backstage/installation).

package/dist/docs/development/guides/domains/05-entities/_category_.json

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

package/dist/docs/development/guides/domains/08-domain-integration-map.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 7
+keywords:
+    - domain integration map
+    - domains
+sidebar_label: Domain Integration Map
+title: Domain Integration Map
+description: Component list for domains 
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.45.0" />
+
+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)
+
+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.
+
+## How it works?
+
+EventCatalog will visualize messages that are being sent between domains in EventCatalog.
+
+As you write domains, services and messages in EventCatalog, some of these communications will be cross domain and boundary.
+This can be intentional or accidental.
+
+Using the Domain Integration Map, you can see these cross-domain communications and understand the dependencies between domains.
+
+
+## How to see the Global Domain Integration Map
+
+To see the Domain integration map, you need at least one domain in your EventCatalog.
+
+1. Click on the **Global Domain Integration Map** section in the navigation bar for any domain in your EventCatalog.
+
+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/_category_.json

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

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

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+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';
+
+<AddedIn version="2.5.0" />
+
+Flows are a way to document business workflows in your organization. You can reuse your documented resources (e.g services, messages, data stores) in your flows.
+
+An example of a flow would be when a user makes a payment to an e-commence system, this interaction triggers many parts of the architecture (services, external services, commands, queries and events):
+
+1. User requests to make payment (e.g MakePayment Command)
+1. Command is sent to Payment Service (e.g Payment Service)
+1. Payment service will either accept or reject payment (e.g PaymentAccepted / PaymentRejected events)
+1. Notification service listens to these events and sends Emails (e.g EmailSent Event)
+1. User will be notified of payment success/failure
+
+### Example
+
+![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/flows/02-adding-flows.md

@@ -0,0 +1,198 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog flows
+sidebar_label: Creating a flow
+title: Creating flows
+description: Creating and managing flows within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.5.0" />
+
+Flows live in a `/flows` folder. EventCatalog will discover 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: `/flows/{Flow Name}/index.mdx`
+- Inside a domain: `/domains/Orders/flows/{Flow Name}/index.mdx`
+- Inside a service: `/services/PaymentService/flows/{Flow Name}/index.mdx`
+- In subdirectories to group related flows: `/flows/Payments/{Flow Name}/index.mdx`
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_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 event will automatically appear across EventCatalog.
+
+## Organize with subdirectories
+
+You can group related flows by placing them in subdirectories inside any `flows` folder. EventCatalog will discover them regardless of nesting depth.
+
+```
+flows/
+  Payments/
+    ProcessPayment/
+      index.mdx
+    RefundPayment/
+      index.mdx
+  Subscriptions/
+    CancelSubscription/
+      index.mdx
+```
+
+The flow `id` in your frontmatter is what EventCatalog uses for routing and references. The directory structure is purely for organization.
+
+## Add badges
+
+Badges appear on the flow page and in catalog listings. Use them to label flows by category, status, or team, and users can filter flows by badge.
+
+```md title="Example"
+---
+id: ProcessPayment
+name: Process Payment
+version: 1.0.0
+badges:
+  - content: Payments
+    backgroundColor: blue
+    textColor: blue
+  - content: Critical
+    backgroundColor: red
+    textColor: red
+---
+```
+
+## Write flow content
+
+You can write any Markdown inside a flow.
+
+Each flow gets its own page, so use this space to fully explain how it works.
+
+You can also use [interactive components](/docs/development/components/using-components) to enrich your documentation.
+
+## Add child flows / reusable flows
+
+<AddedIn version="2.34.2" />
+
+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.
+
+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
+
+<AddedIn version="3.29.0" />
+
+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?
+
+### What do flows look like in EventCatalog?
+
+![Example](../img/flows/flow-example.png)
+
+[See a flow example](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0).