@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/development/guides/diagrams/05-comparing-diagrams.md

@@ -0,0 +1,145 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog diagrams
+- Diagram comparison
+- EventCatalog Scale
+sidebar_label: Comparing diagrams
+title: Comparing diagram versions (Scale)
+description: Side-by-side version comparison for diagrams with EventCatalog Scale
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+:::info EventCatalog Scale Feature
+Diagram comparison is available exclusively with the [EventCatalog Scale](/docs/development/deployment/licenses) license. This feature enables side-by-side visualization of different diagram versions.
+:::
+
+The diagram comparison feature allows you to view two versions of a diagram side-by-side, making it easy to understand architectural changes and evolution over time.
+
+## When to use diagram comparison
+
+Diagram comparison is valuable for:
+
+- **Migration planning** - Compare current state vs. target state architectures
+- **Change reviews** - Visualize what changed between architectural iterations
+- **Documentation reviews** - Ensure diagrams accurately reflect system changes
+- **Team communication** - Show stakeholders the architectural progression
+- **Historical analysis** - Understand why architectural decisions were made
+
+## Accessing diagram comparison
+
+When viewing a diagram that has multiple versions, you'll see a "Compare diagram versions" button in the header (only available with Scale license).
+
+![Compare diagram versions](./img/diagrams-compare.png)
+
+### Steps to compare
+
+1. Navigate to any diagram page that has multiple versions
+2. Click the "Compare diagram versions" button in the header
+3. Select which two versions you want to compare
+4. View both diagrams side-by-side with synchronized scrolling
+
+## Example use cases
+
+### Comparing migration states
+
+Compare your current monolithic architecture with your target microservices architecture:
+
+**Version 1.0.0 (Current State):**
+- Monolithic application
+- Single database
+- Tightly coupled components
+
+**Version 2.0.0 (Target State):**
+- Event-driven microservices
+- Database per service
+- Kafka event backbone
+
+Viewing these side-by-side helps teams understand the scope of the migration and communicate the changes to stakeholders.
+
+### Tracking architectural evolution
+
+Compare different iterations of your architecture as it evolves:
+
+**Version 1.0.0:**
+- Initial MVP architecture
+- 3 core services
+
+**Version 1.5.0:**
+- Added caching layer
+- Introduced API gateway
+- Split user service
+
+**Version 2.0.0:**
+- Full event-driven architecture
+- 12 microservices
+- Observability platform
+
+### Reviewing sequence flow changes
+
+Compare how a business flow has changed between versions:
+
+**Version 1.0.0 - Synchronous Order Flow:**
+Shows direct HTTP calls between services
+
+**Version 2.0.0 - Event-Driven Order Flow:**
+Shows asynchronous event-based communication
+
+This makes it clear how the system's behavior and coupling has evolved.
+
+## Comparison UI features
+
+The comparison view provides:
+
+- **Side-by-side layout** - Both diagrams displayed simultaneously
+- **Version labels** - Clear indication of which version is shown on each side
+- **Synchronized scrolling** - Scroll both diagrams together (optional)
+- **Full content** - All markdown content and diagrams from both versions
+- **Independent navigation** - Switch versions independently on each side
+
+![Compare diagram versions](./img/diagrams-compare.png)
+
+## Best practices
+
+### Prepare diagrams for comparison
+
+When creating diagrams you plan to compare:
+
+1. **Use consistent formatting** - Keep similar elements in the same positions when possible
+2. **Highlight changes** - Use annotations or callouts to draw attention to differences
+3. **Add context** - Include notes explaining what changed and why
+4. **Match diagram types** - Compare sequence diagrams with sequence diagrams, architecture diagrams with architecture diagrams
+
+### Document what changed
+
+In your diagram content, call out the key differences:
+
+```md title="Version 2.0.0 diagram with change notes"
+---
+id: order-flow
+name: Order Processing Flow
+version: 2.0.0
+summary: Event-driven order processing (updated for async architecture)
+---
+
+## What Changed in v2.0.0
+
+Compared to version 1.0.0, this flow now uses event-driven architecture:
+
+- **Removed**: Synchronous HTTP calls between services
+- **Added**: Kafka event stream for service communication
+- **Changed**: Order Service now publishes OrderCreated event instead of calling downstream services directly
+- **Benefit**: Improved resilience and scalability
+
+_```mermaid
+sequenceDiagram
+    Customer->>OrderService: Place Order
+    OrderService->>Kafka: Publish OrderCreated
+    Kafka->>InventoryService: OrderCreated Event
+    Kafka->>PaymentService: OrderCreated Event
+```_
+```
+

package/dist/docs/development/guides/diagrams/06-diagrams-with-llms.md

@@ -0,0 +1,165 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog diagrams
+- LLMs
+- AI
+- Markdown export
+- llms.txt
+sidebar_label: Diagrams with LLMs
+title: Using diagrams with LLMs
+description: How to use your diagrams with AI assistants and LLM tools
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+EventCatalog makes your diagrams accessible to AI assistants and LLM tools, enabling you to ask questions about your architecture and get contextual answers.
+
+## How it works
+
+Every diagram in EventCatalog is available as a markdown file at a `.mdx` endpoint. This follows the [llms.txt](https://llmstxt.org/) convention, making your diagrams consumable by AI tools.
+
+```
+# Diagram page (rendered)
+/diagrams/system-overview/1.0.0
+
+# Markdown version (for LLMs)
+/diagrams/system-overview/1.0.0.mdx
+```
+
+The markdown export includes:
+- Frontmatter (id, name, version, summary)
+- All diagram content (Mermaid, PlantUML, markdown)
+- Any documentation you've added
+
+## Using with EventCatalog Assistant
+
+With EventCatalog's AI assistant (Starter/Scale), you can ask questions about your diagrams directly from the diagram page.
+
+![EventCatalog Assistant](./img/diagrams-ai.png)
+
+Click the "Ask about this diagram" button to open the assistant with context about the current diagram. Example questions:
+
+- "What services are shown in this diagram?"
+- "Explain the flow between OrderService and PaymentService"
+- "What would happen if the Kafka cluster went down?"
+- "How does this compare to the previous version?"
+
+## Using with external LLM tools
+
+You can use the `.mdx` endpoints with any LLM tool that supports fetching content:
+
+### Claude, ChatGPT, or other assistants
+
+Share the `.mdx` URL directly:
+
+```
+Here's my system architecture diagram:
+https://your-catalog.com/diagrams/system-overview/1.0.0.mdx
+
+Can you explain the data flow?
+```
+
+### MCP servers
+
+If you're using EventCatalog's MCP server, your diagrams are automatically available to compatible AI tools like Claude Desktop.
+
+### Custom integrations
+
+Fetch diagram content programmatically:
+
+```bash
+curl https://your-catalog.com/diagrams/system-overview/1.0.0.mdx
+```
+
+## All versions are accessible
+
+Every version of your diagram has its own `.mdx` endpoint:
+
+```
+/diagrams/architecture/2.0.0.mdx  # Latest
+/diagrams/architecture/1.5.0.mdx  # Previous
+/diagrams/architecture/1.0.0.mdx  # Initial
+```
+
+This lets you ask AI tools to compare versions or explain how your architecture evolved:
+
+```
+Compare these two versions of our architecture:
+- Current: https://catalog.com/diagrams/architecture/1.0.0.mdx
+- Target: https://catalog.com/diagrams/architecture/2.0.0.mdx
+
+What are the main differences?
+```
+
+## Tips for LLM-friendly diagrams
+
+To get the most out of AI interactions with your diagrams:
+
+### Add context in markdown
+
+Don't just include the diagram - add explanations:
+
+```md
+## System Overview
+
+This diagram shows our order processing architecture.
+
+### Key Components
+
+- **OrderService**: Handles order creation and lifecycle
+- **PaymentService**: Processes payments via Stripe
+- **Kafka**: Event backbone for async communication
+
+### Important Notes
+
+- All services are deployed to Kubernetes
+- Database connections use connection pooling
+- Events are retained for 7 days
+
+\`\`\`mermaid
+graph TB
+    ...
+\`\`\`
+```
+
+### Use descriptive labels
+
+In your diagrams, use clear, descriptive names:
+
+```
+# Good - descriptive labels
+OrderService[Order Service]
+PaymentDB[(Payments Database)]
+
+# Avoid - cryptic abbreviations
+OS[OS]
+PDB[(PDB)]
+```
+
+### Document relationships
+
+Explain why components connect, not just that they do:
+
+```md
+The Order Service publishes `OrderCreated` events to Kafka.
+The Payment Service subscribes to these events to initiate payment processing.
+This decoupled design allows independent scaling and deployment.
+```
+
+## Enabling markdown export
+
+Markdown export is enabled by default. To disable it, update your `eventcatalog.config.js`:
+
+```js
+export default {
+  // ...
+  llmsTxt: {
+    enabled: false
+  }
+}
+```
+
+When enabled, all resources (including diagrams) are accessible via `.mdx` endpoints.

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

@@ -0,0 +1,10 @@
+{
+  "label": "Diagrams",
+  "position": 10,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how to document your architecture with reusable diagrams"
+  }
+}

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

@@ -0,0 +1,22 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog events
+sidebar_label: What are domains?
+title: Understanding domains
+description: What are domains? Why are they useful for event-driven architectures?
+---
+
+Domain-Driven Design (DDD) is a software development approach that focuses on deeply understanding and accurately modelling the business domain. This methodology aims to enhance software quality by ensuring it aligns closely with the business requirements it supports. Eric Evans introduced DDD to the software development community in 2003 through his influential book, [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).
+
+The essence of domain-driven design lies in managing complexity by centering software development around the ‘domain,’ which is the specific business context where the software is used. DDD promotes the use of a [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), a shared vocabulary between developers and business stakeholders. This common language is used throughout the design and implementation process, ensuring that the software accurately represents the business domain it is designed to serve.
+
+Domain-driven design has some core building blocks including entities, value objects, bounded context and aggregates.
+
+**EventCatalog uses domains as a way to group services into a bounded context.**
+
+**EventCatalog support subdomains, which can be used to group domains together.**
+
+Using domains in EventCatalog gives you a better way to manage your services and define their bounded context. 
+
+Domains can also directly specify the messages they send and receive, providing a high-level view of domain interactions.

package/dist/docs/development/guides/domains/02-creating-domains/02-adding-domains.md

@@ -0,0 +1,108 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating a domain
+title: Creating domains
+description: Creating and managing domains within EventCatalog.
+---
+
+Domains are a great way to group your documentation into logical units that can be represented in your organization.
+
+EventCatalog Domains are inspired by the [Domain-Driven Design](/docs/development/guides/domains/introduction) approach.
+
+In EventCatalog a domain is a logical unit that contains related [services](/docs/development/guides/services/introduction), [entities](/docs/development/guides/domains/entities/introduction), [messages](/docs/development/guides/messages/overview), subdomains,  and other resources.
+
+### What do domains look like in EventCatalog?
+
+![Example](../../img/domains/domain-example.png)
+
+## Adding a new domain
+
+To add a new domain create a new folder within the `/domains` folder with an `index.mdx` file.
+
+- `/domains/{Domain Name}/index.mdx` 
+  - (example `/domains/Orders/index.mdx`)
+
+The `index.mdx` contents are split into two sections, [**frontmatter**](/docs/api/domain-api) and the [**markdown content**](#adding-content).
+
+_Here is an example of what a domain markdown file may look like._
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+# id of your domain, used for slugs and references in EventCatalog.
+id: Orders
+
+# Display name of the domain, rendered in EventCatalog
+name: Orders
+
+# Version of the domain
+version: 0.0.1
+
+# Short summary of your domain
+summary: |
+  Domain that contains order related information
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional services. Groups services into this domain.
+services:
+    - id: PaymentService
+      version: 0.0.1
+
+# Optional flows associated with this domain
+flows:
+    - id: OrderProcessing
+      version: 1.0.0
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New domain
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+Domain that contains all services that are related to the orders domain within FakeCompany.
+
+<NodeGraph />
+
+```
+
+**That's it!**
+
+Once you add your domain it will appear in your catalog.
+
+## Adding content
+
+Your domain page will render the markdown content you add to the file. To add content to your domain page, add markdown to the file.
+
+```md title="/domains/Orders/index.mdx"
+---
+id: Orders
+version: 0.0.1
+name: Orders
+---
+
+## Overview
+
+This is your domain markdown....
+
+You can add anything here...
+
+Including EventCatalog components
+
+<NodeGraph />
+
+```
+
+## Using components
+
+EventCatalog supports [MDX](https://mdxjs.com/) under the hood. This gives you the ability to use components inside your domain page.
+
+You can find a list of EventCatalog components you can use here: [EventCatalog components](/docs/development/components/using-components).
+
+

package/dist/docs/development/guides/domains/02-creating-domains/02a-subdomains.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating subdomains
+title: Creating subdomains
+description: Creating and managing subdomains within EventCatalog.
+id: subdomains
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.34.0" />
+
+Subdomains are optional in EventCatalog but can be a great way to group domains together. 
+
+Some organizations have multiple domains, and each domain may have multiple subdomains.
+
+When you add a subdomain to a domain, your users will be able to see the relationship between the domain and subdomain, and be able to navigate between them.
+
+### What do subdomains look like in EventCatalog?
+
+![Example](../../img/domains/subdomain-example.png)
+
+_See [subdomain example](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
+
+
+#### Domains Visualizer (with subdomains)
+
+When you reference a subdomain from a domain, it will appear in the domains visualizer.
+You can use the legend to highlight resources that are part of a subdomain.
+
+![Domains Visualizer (with subdomains)](../../img/domains/subdomain-visualizer.png)
+
+_See [subdomain example](https://demo.eventcatalog.dev/visualiser/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
+
+## Adding subdomains
+
+A subdomain is just another domain resource. But a parent domain references the subdomains.
+
+First you need to create your subdomain.
+
+You can create a subdomain in the `/domains` folder or in a `/subdomains` folder.
+
+**Examples**
+
+1. `/domains/MySubDomain/index.mdx` - Just like any other domain resource.
+2. `/domains/MyParentDomain/subdomains/MySubDomain/index.mdx`
+    - You nest the subdomain within the parent domain. (recommended)
+
+Once you have created your subdomain, you can reference it from your parent domain.
+
+### Referencing subdomains
+
+To add a `subdomain` to a `domain` you need to reference the `subdomain` from the `domain` markdown file.
+
+We do this using the `domains` property.
+
+In this example we are adding the `Orders` and `Customers` subdomains to the `Ecommerce` domain.
+
+```md title="/domains/Ecommerce/index.mdx (example)"
+---
+id: Ecommerce
+name: Ecommerce
+version: 0.0.1
+
+# List of subdomains (version is optional)
+domains:
+  # Here version is given, the latest version of Orders Domain is used.
+  - id: Orders
+    version: 0.0.1
+  # Here version is not given, the latest version of Customers Domain is used.
+  - id: Customers
+---
+
+## Overview
+
+Ecommerce domain contains all ecommerce related information for FakeCompany.
+
+<NodeGraph />
+
+```
+
+Once you add the subdomains to the domain, it will now show in the docs, visualizer and discoverability table.

package/dist/docs/development/guides/domains/02-creating-domains/03-adding-services-to-domains.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog domains
+sidebar_label: Adding services to domains
+title: Adding services to domains
+description: Creating and managing domains within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Adding [services](/docs/development/guides/services/introduction) to your domains is a great way to group services within a particular domain.
+
+When adding services to your domain EventCatalog will:
+
+- Show the services in the domain sidebar
+- Visualize all the services within that domain using the visualizer
+
+## Adding services using frontmatter
+
+To add services within a domain you need to add them to the `services` array within your domain frontmatter API.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+services:
+    # id of the service you want to add
+    - id: PaymentsService
+    # (optional) The version of the service you want to add.
+      version: 0.0.1
+
+    # Note: version is optional. If no version is given the latest version of the service will be used.
+    - id: NotificationsService
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `services` frontmatter in your domain tells EventCatalog that these documented services belong to this domain.
+
+In the example above we can see that the services `PaymentsService` and `NotificationsService` belong to the `PaymentDomain`.
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can also use semver to match the version of the service you want to add.
+
+<details>
+  <summary>Example of using semver versioning</summary>
+
+  ```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+services:
+    # Latest minor version of PaymentsService will be added
+    - id: PaymentsService
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: NotificationsService
+      version: ^1.0.1
+    # Latest version of this service will be shown by default.
+    - id: PaymentsService
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Although it's recommended to link to a version of a service it is now optional. If no version is given **latest** is used by default.
+</details>
+
+
+
+
+### Visualizing services within a domain
+
+When you view your domain in EventCatalog, the services will be visualized for you.
+
+![Example](../../img/domains/visualiser.png)
+
+
+
+## Making changes and versioning
+
+You can make as many changes as you want, but if you are adding/removing services you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why services are coming in/out of a particular domain.
+