@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/bring-your-own-documentation/custom-pages/02-adding-custom-docs.md

@@ -1,64 +1,104 @@
 ---
 sidebar_position: 1
 keywords:
-- EventCatalog global documentation
-sidebar_label: Adding global documentation
-title: Adding global documentation
-description: Adding global documentation to your EventCatalog
+- EventCatalog high level documentation
+sidebar_label: Adding high level documentation
+title: Adding high level documentation
+description: Adding high level documentation to your EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 ## Getting started
 
-Global documentation requires a [Starter or Scale plan](https://eventcatalog.dev/pricing), you can get a 14 day free trial to test it out at [EventCatalog Cloud](https://eventcatalog.cloud). Once you have a license key you can start to use the feature.
+High level documentation requires an EventCatalog Scale license key. You can get a 30-day free trial from [EventCatalog Cloud](https://eventcatalog.cloud).
 
-## Adding global documentation
+## Adding high level documentation
 
-Global documentation is split into two parts:
+High level documentation is split into two parts:
 
 1. [Creating your documentation (markdown files)](#creating-your-documentation)
 2. [Configuring your sidebar (eventcatalog.config.js)](#configuring-your-sidebar)
 
 ### Creating documentation
 
-Global documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.
+High level documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.
 
 All documentation is a `.mdx` (markdown extended) file. You can organize these however you want, for example:
 
-```
-docs/
-├── architecture-decision-records/
-│   ├── drafts/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-│   ├── published/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-│   ├── examples/
-│   │   ├── 01-introduction.mdx
-│   │   ├── 02-example-record.mdx
-├── runbooks/
-│   ├── 01-introduction.mdx
-│   ├── 02-deployment-procedure.mdx
-│   ├── 03-disaster-recovery.mdx
-│   ├── 04-incident-response.mdx
-
-```
+<ProjectTree
+  items={[
+    {
+      name: 'docs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'architecture-decision-records',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'drafts',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'published',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'examples',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'runbooks',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: '01-introduction.mdx' },
+            { name: '02-deployment-procedure.mdx' },
+            { name: '03-disaster-recovery.mdx' },
+            { name: '04-incident-response.mdx' },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
-In this example we have global documentation for:
+In this example we have high level documentation for:
 
 - architecture Decision Records
 - Runbooks
 
-:::tip Organize your global documentation
+:::tip Organize your high level documentation
 We added numbers (01, 02, 03) to the files to help with maintenance, you can configure the order of the files in your configuration.
 :::
 
 
-#### Structure of markdown files for global documentation
+#### Structure of markdown files for high level documentation
 
 Each markdown file is split into two parts:
 
@@ -203,5 +243,3 @@ export default {
 
 
 
-
-

package/dist/docs/development/bring-your-own-documentation/custom-pages/03-components.md

@@ -8,6 +8,10 @@ title: Components
 description: Component list for custom pages 
 ---
 
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
 You can add custom EventCatalog components to your custom pages.
 
 [See the list of components and how to use them](/docs/development/components/using-components).
@@ -50,4 +54,3 @@ In custom documentation pages, `id`, `version`, and `type` are all required. A `
 | `search` | boolean | No | Show or hide the search bar. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
 | `legend` | boolean | No | Show or hide the legend. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
 | `mode` | string | No | `"simple"` or `"full"`. Defaults to `"simple"`. |
-

package/dist/docs/development/bring-your-own-documentation/custom-pages/04-owners.md

@@ -10,8 +10,10 @@ description: Adding owners to custom pages with EventCatalog.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 Owners in EventCatalog are either **users** or **teams** and are **optional**.
 
@@ -42,4 +44,3 @@ Assigning owners to your custom pages can provide others with context of who own
     EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
 :::
 
-

package/dist/docs/development/bring-your-own-documentation/custom-pages/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Global documentation",
+  "label": "High level documentation",
   "position": 2,
   "collapsible": true,
   "collapsed": true,

package/dist/docs/development/bring-your-own-documentation/diagrams/01-introduction.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog diagrams
+- Architecture diagrams
+- Custom diagrams
+- Mermaid
+- PlantUML
+- Miro
+- IcePanel
+sidebar_label: What are diagrams?
+title: What are 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';
+
+You can bring your own diagrams (e.g Miro, DrawIO, Mermaid, PlantUML) into your catalog and assign them to any resource in your catalog.
+
+With diagrams in EventCatalog you can:
+
+- **Bring any diagram type** - Mermaid, PlantUML, Miro embeds, IcePanel, Lucidchart, draw.io, images, or any MDX content
+- **Version and compare your diagrams** - Track how your architecture visualizations evolve over time and compare them
+- **Assign to any resource** - Link to any catalog resource (e.g domain, system, service, message)
+- **Context to your AI** - EventCatalog MCP exposes your diagrams to your AI agents.
+
+<!-- 
+### 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/bring-your-own-documentation/diagrams/02-creating-diagrams.md

@@ -0,0 +1,262 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diagrams
+- Creating diagrams
+sidebar_label: Create a diagram
+title: Create a diagram
+description: How to create and organize diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog Diagrams let's you bring your own diagrams into your Catalog.
+
+![System Architecture diagram](./img/diagrams.png)
+
+## Creating a diagram
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog diagram">
+Read https://www.eventcatalog.dev/docs/development/bring-your-own-documentation/diagrams/creating-diagrams.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/diagrams.md then help me create a new EventCatalog diagram in my catalog.
+
+Ask me for the diagram name, what it shows, summary, whether it belongs at the root of the catalog or inside a resource, and what diagram format I want to use such as Mermaid, PlantUML, an embedded tool, an image, or markdown. Then create the correct diagrams/{'{Diagram Name}'}/index.mdx, domains/{'{Domain Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, services/{'{Service Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, or another relevant resource-level diagrams/{'{Diagram Name}'}/index.mdx file with frontmatter and starter markdown.
+
+If I want to embed an external diagram, ask for the embed URL and use the correct EventCatalog diagram component if one exists.
+
+If the catalog does not have a relevant resource, put it into the root diagrams folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the diagram should live, create the right folder structure, and add the first version of the diagram documentation.
+
+### Manual Creation
+
+Diagrams live in a `diagrams` folder. EventCatalog discovers any `index.mdx` file inside a `diagrams` directory, regardless of where that directory lives in your catalog.
+
+You can place diagrams:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'diagrams',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'system-overview',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'E-Commerce',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'target-architecture',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'api-flow',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::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.
+:::
+
+## Create the diagram file
+
+Create an `index.mdx` file for the diagram.
+
+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
+```
+
+
+### 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 [Diagrams documentation](/docs/components/diagram-syntax) to see all available diagram syntax and embed components including `<Miro>`, `<IcePanel>`, `<Lucid>`, `<DrawIO>`, and `<FigJam>`.
+:::
+
+## Next steps
+
+Once you've created diagrams, you can:
+
+- [Reference them from resources](/docs/development/bring-your-own-documentation/diagrams/referencing-diagrams) like domains, services, and messages
+- [Compare diagram versions](/docs/development/bring-your-own-documentation/diagrams/comparing-diagrams) side-by-side

package/dist/docs/development/{guides → bring-your-own-documentation}/diagrams/03-referencing-diagrams.md

@@ -3,18 +3,12 @@ sidebar_position: 3
 keywords:
 - EventCatalog diagrams
 - Referencing diagrams
-sidebar_label: Referencing diagrams
-title: Referencing diagrams from resources
+sidebar_label: Add diagrams to resources
+title: Add diagrams to 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
+You can assign your diagrams to resources in EventCatalog.
 
 When you reference a diagram from a resource, EventCatalog automatically:
 
@@ -107,74 +101,6 @@ diagrams:
 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:
@@ -183,13 +109,3 @@ When viewing a resource that references diagrams, users will see:
 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/bring-your-own-documentation/diagrams/05-comparing-diagrams.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog diagrams
+- Diagram comparison
+sidebar_label: Compare diagram versions
+title: Comparing diagram versions
+description: Side-by-side version comparison for diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+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.
+
+This can be useful if you want to plan for changes, or track changes over time.
+
+![Compare diagram versions](./img/diagrams-compare.png)
+
+### How to compare diagrams
+
+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
+