@eventcatalog/core 3.35.0 → 3.36.1

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog diagrams
+- Architecture diagrams
+- Custom diagrams
+- Mermaid
+- PlantUML
+- Miro
+- IcePanel
+sidebar_label: Understanding diagrams
+title: Understanding diagrams
+description: Bring your own diagrams to EventCatalog - version them, compare them, and assign them to any resource
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+EventCatalog automatically generates architecture diagrams based on your resources and how they relate to each other. These auto-generated visualizations help you understand your system's structure.
+
+**But what about your own diagrams?**
+
+Many teams have existing architecture diagrams - whether they're Mermaid flowcharts, PlantUML sequence diagrams, Miro boards, IcePanel views, or simple images. The diagrams feature lets you bring these into EventCatalog as first-class, versioned resources.
+
+### What can you do with diagrams?
+
+With diagrams in EventCatalog you can:
+
+- **Bring any diagram type** - Mermaid, PlantUML, Miro embeds, IcePanel, Lucidchart, draw.io, images, or any MDX content
+- **Version your diagrams** - Track how your architecture visualizations evolve over time
+- **Compare versions side-by-side** - See what changed between diagram versions (Scale feature)
+- **Assign to any resource** - Link diagrams to domains, services, messages, or containers
+- **Reuse across resources** - Reference the same diagram from multiple places in your catalog
+- **Organize flexibly** - Store diagrams at the top level or nest them within domains and services
+- **Ask questions with AI** - Use EventCatalog's AI assistant to ask questions about your diagrams
+- **Expose to LLMs** - Diagrams are available at `.mdx` URLs (e.g., `/diagrams/my-diagram/1.0.0.mdx`) for LLM consumption
+
+### How is this different from auto-generated diagrams?
+
+| Auto-generated diagrams | Custom diagrams (this feature) |
+|------------------------|-------------------------------|
+| Created automatically from your resources | You create and maintain them |
+| Show relationships between catalog items | Show anything you want |
+| Update when resources change | Update when you version them |
+| Limited to catalog data | Any visual content |
+
+Both complement each other. Auto-generated diagrams show your system as documented in the catalog. Custom diagrams let you add context - migration plans, target architectures, sequence flows, event storming results, or embedded boards from your favorite diagramming tools.
+
+### What do diagrams look like in EventCatalog?
+
+Diagrams have their own dedicated pages with version switching and appear in the sidebar when assigned to resources.
+
+![Diagram page](./img/diagrams.png)
+
+[View Demo of a Target Architecture diagram &rarr;](https://demo.eventcatalog.dev/diagrams/target-architecture/1.0.0)
+
+### When to use custom diagrams
+
+Use diagrams when you want to:
+
+- Document target architecture or migration plans
+- Embed Miro boards, IcePanel views, or other collaborative diagrams
+- Create sequence diagrams showing detailed message flows
+- Share event storming results or architecture decision records
+- Maintain historical versions of architectural diagrams
+- Add visual context that can't be auto-generated from your resources
+
+### Supported content formats
+
+Diagrams support any content you can write in MDX:
+
+- **Mermaid diagrams** - Flowcharts, sequence diagrams, C4 diagrams
+- **PlantUML diagrams** - UML, sequence, component diagrams
+- **Embedded diagrams** - Miro, IcePanel, Lucidchart, draw.io, FigJam
+- **Static images** - PNG, SVG, JPG files
+- **Markdown content** - Add explanations and documentation around visuals
+- **Custom components** - Use any MDX component to enhance your diagrams

package/dist/docs/development/guides/diagrams/02-creating-diagrams.md

@@ -0,0 +1,195 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diagrams
+- Creating diagrams
+sidebar_label: Creating diagrams
+title: Creating diagrams
+description: How to create and organize diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+Diagrams in EventCatalog are created using MDX files with frontmatter. They can be placed at the root level or nested within any resource (domains, services, events, commands, queries, or containers) for better organization.
+
+## File structure
+
+Diagrams live in a `/diagrams` folder. This folder can be placed at the root level or nested within any resource:
+
+```
+# Root level diagrams
+/diagrams/[diagram-name]/index.mdx
+
+# Nested within any resource (domains, services, events, commands, queries, containers)
+/[resource]/[resource-name]/diagrams/[diagram-name]/index.mdx
+```
+
+**Examples:**
+- `/diagrams/system-overview/index.mdx` - Root level diagram
+- `/domains/E-Commerce/diagrams/target-architecture/index.mdx` - Domain diagram
+- `/services/OrderService/diagrams/api-flow/index.mdx` - Service diagram
+
+:::tip
+Organize diagrams close to where they're most relevant. System-wide diagrams can be placed at the root level, while resource-specific diagrams should live within that resource's folder.
+:::
+
+## Creating a diagram
+
+To create a new diagram, create a folder with an `index.mdx` file. The file consists of two sections: **frontmatter** and **markdown content**.
+
+Here is an example of a system architecture diagram:
+
+```md title="/diagrams/system-overview/index.mdx (example)"
+---
+id: system-overview
+name: System Overview
+version: 1.0.0
+summary: High-level architecture showing all microservices and their interactions
+---
+
+## System Architecture
+
+This diagram shows our microservices architecture:
+
+\`\`\`mermaid
+graph TB
+    subgraph "Frontend"
+        WebApp[Web Application]
+        MobileApp[Mobile App]
+    end
+
+    subgraph "Backend Services"
+        Gateway[API Gateway]
+        OrderService[Order Service]
+        PaymentService[Payment Service]
+        InventoryService[Inventory Service]
+    end
+
+    subgraph "Data Layer"
+        OrderDB[(Orders DB)]
+        PaymentDB[(Payments DB)]
+        Kafka[Event Stream]
+    end
+
+    WebApp --> Gateway
+    MobileApp --> Gateway
+    Gateway --> OrderService
+    Gateway --> PaymentService
+    OrderService --> Kafka
+    PaymentService --> Kafka
+    OrderService --> OrderDB
+    PaymentService --> PaymentDB
+\`\`\`
+
+### Key Components
+
+- **API Gateway**: Single entry point for all client requests
+- **Order Service**: Handles order creation and management
+- **Payment Service**: Processes payments and refunds
+- **Event Stream**: Kafka for asynchronous communication
+```
+
+![System Architecture diagram](./img/diagrams.png)
+
+## Frontmatter properties
+
+Diagrams support the following frontmatter properties:
+
+### Required fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier for the diagram (used in URLs and references) |
+| `name` | `string` | Display name shown in the UI |
+| `version` | `string` | Version of the diagram (e.g., "1.0.0") |
+
+### Optional fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `summary` | `string` | Brief description shown in listings and headers |
+
+## Adding content
+
+The content section of your diagram file supports full MDX, allowing you to:
+
+- Render Mermaid and PlantUML diagrams
+- Embed diagrams from external tools (Miro, Lucidchart, etc.)
+- Add explanatory text and documentation
+- Include images and other media
+- Use EventCatalog components for enhanced functionality
+
+### Example with PlantUML
+
+```md title="/diagrams/order-flow/index.mdx (example)"
+---
+id: order-flow
+name: Order Processing Flow
+version: 1.0.0
+summary: Sequence diagram showing the complete order processing flow
+---
+
+\`\`\`plantuml
+@startuml
+actor Customer
+participant "Order Service" as Order
+participant "Payment Service" as Payment
+participant "Inventory Service" as Inventory
+
+Customer -> Order: Create Order
+Order -> Inventory: Check Stock
+Inventory --> Order: Stock Available
+Order -> Payment: Process Payment
+Payment --> Order: Payment Confirmed
+Order --> Customer: Order Confirmed
+@enduml
+\`\`\`
+
+## Order Processing Flow
+
+This sequence diagram illustrates the order processing workflow:
+
+1. Customer initiates order creation
+2. Order service validates inventory availability
+3. Payment is processed
+4. Order confirmation is sent to customer
+```
+
+### Example with embedded diagram
+
+EventCatalog provides built-in components to embed diagrams from popular tools like Miro, IcePanel, Lucidchart, draw.io, and FigJam. This lets you bring your existing collaborative diagrams directly into your catalog.
+
+```md title="/diagrams/architecture-overview/index.mdx (example)"
+---
+id: architecture-overview
+name: Architecture Overview
+version: 1.0.0
+summary: Miro board showing our system architecture and design decisions
+---
+
+<Miro embedUrl="https://miro.com/app/board/..." />
+
+## Architecture Overview
+
+This Miro board captures our architecture decisions and system design.
+Key areas covered:
+
+- System context
+- Container architecture
+- Component relationships
+- Technology choices
+```
+
+:::tip
+Check out the [MDX components documentation](/docs/components/external-diagram-embeds) to see all available embed components including `<Miro>`, `<IcePanel>`, `<Lucid>`, `<DrawIO>`, and `<FigJam>`.
+:::
+
+## Next steps
+
+Once you've created diagrams, you can:
+
+- [Reference them from resources](/docs/development/guides/diagrams/referencing-diagrams) like domains, services, and messages
+- [Create versioned diagrams](/docs/development/guides/diagrams/versioning-diagrams) to track architectural evolution
+- Use the Scale license to [compare diagram versions](/docs/development/guides/diagrams/comparing-diagrams) side-by-side

package/dist/docs/development/guides/diagrams/03-referencing-diagrams.md

@@ -0,0 +1,195 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog diagrams
+- Referencing diagrams
+sidebar_label: Referencing diagrams
+title: Referencing diagrams from resources
+description: How to link diagrams to domains, services, messages, and other resources
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+One of the key benefits of diagrams in EventCatalog is that they can be referenced from multiple resources. This allows you to create reusable visual documentation that appears in the sidebar of your domains, services, messages, and containers.
+
+## How diagram references work
+
+When you reference a diagram from a resource, EventCatalog automatically:
+
+- Adds the diagram to the resource's sidebar under a "Diagrams" section
+- Creates a clickable link to the full diagram page
+- Shows the diagram name and summary in the sidebar
+
+<div className="flex justify-center">
+  <img src="/img/diagram-sidebar.png" alt="Diagram references" className="rounded-lg" style={{ width: '20%', height: 'auto' }} />
+</div>
+
+## Referencing diagrams in frontmatter
+
+To reference diagrams from any resource, use the `diagrams` field in the frontmatter:
+
+```yaml
+diagrams:
+  - id: diagram-id
+    # version is optional and defaults to latest if not specified
+    version: 1.0.0
+```
+
+The `version` field is optional and defaults to `latest` if not specified.
+
+## Examples
+
+### Referencing diagrams from a domain
+
+Domain-level diagrams often show the overall architecture, domain boundaries, or integration patterns.
+
+```md title="/domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce Domain
+version: 1.0.0
+summary: Core business domain for our e-commerce platform
+diagrams:
+  - id: target-architecture
+    version: 1.0.0
+  - id: order-flow
+    version: 1.0.0
+---
+
+## Overview
+
+The E-Commerce domain handles all order processing...
+```
+
+When users view the E-Commerce domain, they'll see a "Diagrams" section in the sidebar with links to both the "Target Architecture" and "Order Flow" diagrams.
+
+### Referencing diagrams from a service
+
+Service-level diagrams typically show API flows, service interactions, or internal component architecture.
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 2.0.0
+summary: Manages order lifecycle and orchestration
+diagrams:
+  - id: order-api-flow
+    version: 2.0.0
+  - id: order-state-machine
+    version: 1.0.0
+---
+
+## Overview
+
+The Order Service is responsible for...
+```
+
+### Referencing diagrams from a message
+
+Message-level diagrams can show sequence flows, event propagation, or payload structures.
+
+```md title="/events/OrderCreated/index.mdx"
+---
+id: OrderCreated
+name: Order Created
+version: 1.0.0
+summary: Published when a new order is created
+diagrams:
+  - id: order-creation-flow
+    version: 1.0.0
+---
+
+## Event Details
+
+This event is published when...
+```
+
+### Referencing diagrams from a container
+
+Container-level diagrams often illustrate data models, schema relationships, or access patterns.
+
+```md title="/containers/OrdersDatabase/index.mdx"
+---
+id: OrdersDatabase
+name: Orders Database
+version: 1.0.0
+container_type: database
+technology: PostgreSQL 14
+diagrams:
+  - id: orders-schema-diagram
+    version: 1.0.0
+  - id: data-access-patterns
+    version: 1.0.0
+---
+
+## Database Overview
+
+The Orders database stores...
+```
+
+## Diagram versioning in references
+
+You can reference specific versions of diagrams or use `latest` to always point to the most recent version:
+
+```yaml
+diagrams:
+  # Reference a specific version
+  - id: system-architecture
+    version: 2.1.0
+
+  # Reference the latest version (default if version is omitted)
+  - id: api-flow
+    version: latest
+
+  # Version field is optional - defaults to latest
+  - id: sequence-diagram
+```
+
+:::tip
+Use specific versions when you want to preserve historical accuracy (e.g., showing the architecture as it was at that resource version). Use `latest` when the diagram is continuously updated and you always want to show the current state.
+:::
+
+## Organizing diagram references
+
+For resources with multiple diagrams, organize them logically:
+
+```yaml
+diagrams:
+  # High-level overviews first
+  - id: domain-context
+    version: 1.0.0
+
+  # Detailed flows second
+  - id: checkout-flow
+    version: 2.0.0
+  - id: payment-flow
+    version: 2.0.0
+
+  # Implementation details last
+  - id: database-schema
+    version: 1.5.0
+```
+
+The diagrams will appear in the sidebar in the order you list them.
+
+## Viewing referenced diagrams
+
+When viewing a resource that references diagrams, users will see:
+
+1. A "Diagrams" section in the sidebar navigation
+2. Each diagram listed with its name
+3. Clicking a diagram navigates to the full diagram page
+4. The diagram page includes version selection and full content
+
+## Diagram reusability
+
+The same diagram can be referenced from multiple resources. For example, a "System Context" diagram might be referenced from:
+
+- The main domain
+- Multiple services within that domain
+- The architecture documentation
+
+This reusability ensures consistency and reduces duplication while allowing teams to organize documentation in the way that makes most sense for their use case.

package/dist/docs/development/guides/diagrams/04-versioning-diagrams.md

@@ -0,0 +1,204 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog diagrams
+- Diagram versioning
+sidebar_label: Versioning diagrams
+title: Versioning diagrams
+description: How to create and manage versioned diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.3.0" />
+
+Diagrams in EventCatalog support versioning, allowing you to track how your architecture visualizations evolve over time. This is particularly valuable for maintaining historical accuracy and showing architectural progression.
+
+## Why version diagrams?
+
+Versioning diagrams helps you:
+
+- **Track architectural evolution** - Show how your system design has changed over time
+- **Maintain historical accuracy** - Preserve diagrams as they existed at specific points
+- **Compare versions** - See what changed between different architectural states
+- **Align with resource versions** - Match diagram versions to corresponding service or domain versions
+- **Document migrations** - Illustrate the journey from current state to target state
+
+## Creating versioned diagrams
+
+Similar to other resources in EventCatalog, diagrams use a `versioned` folder structure to maintain multiple versions.
+
+### File structure
+
+```
+/diagrams/
+  └── system-architecture/
+      ├── index.mdx                    # Latest version (e.g., 2.0.0)
+      └── versioned/
+          ├── 1.0.0/
+          │   └── index.mdx            # Version 1.0.0
+          └── 1.5.0/
+              └── index.mdx            # Version 1.5.0
+```
+
+The diagram at the root level (`/diagrams/system-architecture/index.mdx`) represents the **latest version**. Older versions are stored in the `versioned` folder, each in their own version directory.
+
+### Example: Current state vs. target state
+
+A common use case is documenting both your current architecture and your target architecture as different versions:
+
+```md title="/diagrams/architecture/index.mdx (v2.0.0 - Target State)"
+---
+id: architecture
+name: System Architecture
+version: 2.0.0
+summary: Target microservices architecture we are migrating towards
+---
+
+## Target State (v2.0.0)
+
+This is our target architecture - the event-driven microservices platform we are actively migrating towards.
+
+\`\`\`mermaid
+graph TB
+    WebApp[Web Application]
+    Gateway[API Gateway]
+
+    subgraph "Microservices"
+        OrderService[Order Service]
+        PaymentService[Payment Service]
+        InventoryService[Inventory Service]
+    end
+
+    Kafka[Event Stream]
+
+    WebApp --> Gateway
+    Gateway --> OrderService
+    Gateway --> PaymentService
+    Gateway --> InventoryService
+
+    OrderService --> Kafka
+    PaymentService --> Kafka
+    InventoryService --> Kafka
+\`\`\`
+
+### Expected Outcomes
+
+- 10x faster deployments
+- 99.9% availability
+- 50% cost reduction through auto-scaling
+```
+
+```md title="/diagrams/architecture/versioned/1.0.0/index.mdx (v1.0.0 - Current State)"
+---
+id: architecture
+name: System Architecture
+version: 1.0.0
+summary: Current monolithic architecture (legacy system)
+---
+
+## Current State (v1.0.0)
+
+This represents our current monolithic architecture that we are migrating away from.
+
+_```mermaid
+graph TB
+    WebApp[Web Application]
+    Monolith[Monolithic Application]
+    Database[(Single Database)]
+
+    WebApp --> Monolith
+    Monolith --> Database
+```
+
+### Current Limitations
+
+- Single deployment unit
+- Scaling challenges
+- Technology constraints
+```
+
+## Version switching
+
+When viewing a diagram that has multiple versions, EventCatalog displays a version dropdown in the header. Users can:
+
+1. See all available versions in the dropdown
+2. Switch between versions to compare changes
+3. The URL updates to reflect the selected version (e.g., `/diagrams/architecture/2.0.0`)
+
+The latest version is clearly marked in the dropdown with a "(latest)" indicator.
+
+## Referencing specific versions
+
+When referencing diagrams from resources, you can specify which version to link to:
+
+```yaml title="Domain referencing specific diagram versions"
+---
+id: E-Commerce
+name: E-Commerce Domain
+version: 1.0.0
+diagrams:
+  # Reference the current state
+  - id: architecture
+    version: 1.0.0
+---
+```
+
+As you update your domain to newer versions, you can update the diagram reference to match:
+
+```yaml title="Updated domain referencing target architecture"
+---
+id: E-Commerce
+name: E-Commerce Domain
+version: 2.0.0
+diagrams:
+  # Reference the target state
+  - id: architecture
+    version: 2.0.0
+---
+```
+
+## Best practices
+
+### Version numbering
+
+Follow semantic versioning principles:
+
+- **Major version** (2.0.0) - Significant architectural changes (e.g., monolith to microservices)
+- **Minor version** (1.1.0) - New services or components added
+- **Patch version** (1.0.1) - Small corrections or clarifications to the diagram
+
+### When to create new versions
+
+Create a new diagram version when:
+
+- The architecture fundamentally changes
+- Major components are added or removed
+- You want to preserve a snapshot for historical reference
+- You're planning a migration and want to document both states
+
+### Keep versions aligned
+
+When possible, align diagram versions with the resources they document:
+
+```yaml
+# Service at version 2.0.0
+---
+id: OrderService
+version: 2.0.0
+diagrams:
+  # Reference matching diagram version
+  - id: order-service-architecture
+    version: 2.0.0
+---
+```
+
+## Markdown export for all versions
+
+All diagram versions support markdown export, making them accessible to LLM tools and AI assistants. Each version has its own `.mdx` endpoint:
+
+- `/diagrams/architecture/2.0.0.mdx` - Latest version
+- `/diagrams/architecture/1.0.0.mdx` - Version 1.0.0
+- `/diagrams/architecture/1.5.0.mdx` - Version 1.5.0
+
+This allows AI tools to understand the full context of your architectural evolution.