@eventcatalog/core 4.1.3 → 4.1.5

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

@@ -1,195 +0,0 @@
----
-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/04-versioning-diagrams.md

@@ -1,204 +0,0 @@
----
-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.

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

@@ -1,145 +0,0 @@
----
-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/license-keys/plans) 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

@@ -1,165 +0,0 @@
----
-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.