@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/miro/guides/02-creating-new-resources.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+sidebar_label: Creating new resources
+title: "Creating New Resources"
+description: Create new services, events, and other resources directly from the Miro app
+slug: /miro/creating-resources
+---
+
+You can create new resources directly in the Miro app — useful for designing services, events, and other resources that don't exist in your catalog yet.
+
+### Creating from the resource list
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/new-resource.png" alt="New Service" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Creating a new resource</span>
+</div>
+
+1. Click a category (e.g. **Services**) to open the resource list
+2. Click the **+ New** button in the header
+3. A new resource is created with a default name (e.g. "New Service") and version `1.0.0`
+4. The resource is added to both the sidebar list and the Miro board
+
+The new resource appears at the top of the list with a slide-in animation so you can spot it easily.
+
+### Creating from the dashboard
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/dragging-resources.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+
+You can also drag a category card from the dashboard directly onto the board. This creates a new blank resource of that type at the drop position — a quick way to sketch out new resources without opening the category list first.
+
+### Editing new resources
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/edit-resource.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+Once created, click the resource on the board to open its detail view. From there you can edit:
+
+- **Name** — click the pencil icon next to the name to rename it
+- **Version** — click the pencil icon next to the version to change it
+- **Summary** — click the pencil icon next to the summary to add a description
+
+Changes sync to both the sidebar and the board item automatically. Press **Enter** to save or **Escape** to cancel.
+
+### Deleting resources
+
+To remove a resource, you have two options:
+
+- **From the resource list** — hover over a resource and click the trash icon on the right
+- **From the detail view** — select a node on the board, then click the trash icon in the top-right of the detail panel
+
+Deleting from the detail view removes the resource from both the catalog and the Miro board.
+
+### Draft resources
+
+New resources created in the app are marked as drafts. This distinguishes them from resources that were imported from your EventCatalog project, making it easy to see what's new versus what already exists in your architecture.

package/dist/docs/miro/guides/03-editing-resources.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+sidebar_label: Editing resources
+title: "Editing Resources"
+description: Edit resource details by selecting nodes on the board
+slug: /miro/editing-resources
+---
+
+Select any node on the Miro board to view and edit its details in the app panel.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/edit-resource.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Viewing resource details
+
+Click any resource node on the board to open its detail view in the panel. You'll see:
+
+- **Category** — the resource type (Service, Event, Command, etc.)
+- **Name** — the resource name
+- **Version** — the current version
+- **Summary** — a short description
+- **Badges** — tags and labels on the resource
+- **Connected resources** — incoming and outgoing connections grouped by type
+
+For services, connections are organized into:
+- **Incoming Messages** — events, commands, and queries the service receives
+- **Outgoing Messages** — events, commands, and queries the service sends
+- **Data Stores** — databases the service reads from or writes to
+
+For messages, connections show **Producers** and **Consumers**.
+
+### Editing fields
+
+Click the pencil icon next to any editable field to modify it:
+
+- **Name** — updates the resource name on both the board and in the catalog
+- **Version** — updates the version number
+- **Summary** — updates the description
+
+Press **Enter** to save your changes or **Escape** to cancel. Changes are synced to the Miro board item automatically.
+
+### Adding and removing badges
+
+You can add badges to any resource by typing in the badge input field and pressing **Enter**. Click the **x** on a badge to remove it. Badges are useful for tagging resources with metadata like team ownership, status, or technology.
+
+### Deleting resources
+
+Click the trash icon in the top-right of the detail panel to delete the resource. This removes it from both the catalog and the Miro board. You can also select a node on the board and press **Backspace** or **Delete** to remove it.

package/dist/docs/miro/guides/04-connected-resources.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 4
+sidebar_label: Connected resources
+title: "Connected Resources"
+description: View and navigate connections between resources on the board
+slug: /miro/connected-resources
+---
+
+When you draw a connector between two resources on the Miro board, the app automatically labels it and styles it based on the resource types — no manual labeling needed.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/connectors.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Drawing connections
+
+Use Miro's built-in connector tool to draw a line from one resource to another. The app detects the resource types and automatically sets:
+
+- **Label** — describes the relationship (e.g. "publishes event", "receives", "writes to")
+- **Color** — matches the connection type
+- **Shape** — elbowed connectors with directional arrows
+
+### Automatic labels
+
+The label applied depends on the direction and types of the connected resources:
+
+| From | To | Label |
+|------|----|-------|
+| Service | Event / Command / Query | "publishes event", "invokes command", "requests" |
+| Event / Command / Query | Service | "receives event", "accepts", "accepts" |
+| Service | Channel | "publishes to" |
+| Channel | Service | "subscribes from" |
+| Event / Command / Query | Channel | "routed through" |
+| Channel | Event / Command / Query | "delivers" |
+| Service | Data Store | "writes to" |
+| Data Store | Service | "reads from" |
+| Service | Service | "connects to" |
+
+### Viewing connections
+
+Select a resource on the board to see all its connections in the detail panel. Connections are grouped by direction:
+
+- **Services** show Incoming Messages, Outgoing Messages, and Data Stores
+- **Events, Commands, Queries** show Producers and Consumers
+- **Channels** show incoming and outgoing routes
+
+### Connection highlighting
+
+When you select a resource, all of its connections are highlighted in purple on the board. This makes it easy to trace the flow of a message or see which resources depend on the selected one.
+
+### Navigating connections
+
+Click any connected resource in the detail panel to zoom to it on the board and open its details. This lets you follow the message flow through your architecture — from producer to event to consumer — without manually searching the board.

package/dist/docs/miro/guides/05-services-and-dependencies.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+sidebar_label: Services and Dependencies
+title: "Services and Dependencies"
+description: Control whether services are added with their full dependency graph or standalone
+slug: /miro/services-and-dependencies
+---
+
+When you drag a service onto the board, you can choose whether to add just the service itself or its entire dependency graph — messages, channels, data stores, and related services.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/services-with-deps.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+
+### The dependencies toggle
+
+In the services list view, you'll find a checkbox labeled **Include dependencies when adding to board**.
+
+- **Checked** — dragging a service onto the board also adds all of its connected resources and the connections between them
+- **Unchecked** — only the service node is added to the board, with no dependencies
+
+This setting is remembered between sessions.
+
+### What gets included with dependencies
+
+When the toggle is enabled and you drag a service onto the board, the app automatically adds:
+
+- **Messages** — all events, commands, and queries that the service sends or receives
+- **Channels** — any message brokers or routing channels between the service and its messages
+- **Data Stores** — databases the service reads from or writes to, with labeled connections (reads, writes, or reads & writes)
+- **Related Services** — other services that produce or consume the same messages, so you can see the full communication flow
+
+All connections are drawn automatically with descriptive labels like "publishes event", "receives", "accepts", "writes to", etc.
+
+### When to use each mode
+
+#### With dependencies
+
+Use this when you want to see the full picture of how a service fits into your architecture. This is useful for:
+
+- Understanding the impact of changing a service
+- Onboarding new team members to a service's role in the system
+- Planning migrations that affect multiple services
+
+#### Without dependencies
+
+Use this when you want to manually compose your board — for example:
+
+- Designing a new architecture from scratch
+- Placing specific services side by side for comparison
+- Building a simplified view that only shows certain resources
+- Adding services one at a time and drawing connections manually

package/dist/docs/miro/guides/06-navigating-the-board.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 5
+sidebar_label: Navigating the Board
+title: "Navigating the Board"
+description: Navigate between connected resources and organize your board layout
+slug: /miro/navigating-the-board
+---
+
+As your board grows, the Miro app provides several ways to navigate between resources and keep things organized.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/navigation.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Clicking connected resources
+
+When viewing a resource's detail panel, you'll see its incoming and outgoing connections listed. Click any connected resource to:
+
+1. **Zoom** to that resource on the board
+2. **Select** it so its detail panel opens automatically
+
+This lets you follow the flow of messages through your architecture — click from a service to an event it publishes, then to the service that consumes it, and so on.
+
+### Finding resources from the list
+
+When browsing the resource list in the sidebar, hover over any resource to reveal a **crosshair icon**. Click it to zoom directly to that resource on the board — helpful when you have a large board and need to locate a specific resource.
+
+### Auto-layout
+
+If your board gets cluttered, click the **Auto-layout** button in the dashboard header. This automatically arranges all resources using a left-to-right directed graph layout, organizing connected resources into a clean flow.
+
+Auto-layout is useful after:
+- Adding several resources with dependencies at once
+- Manually moving things around and wanting to reset the layout
+- Getting a clear picture of the overall architecture flow
+
+### Auto-opening the panel
+
+When you select a node on the board, the app panel automatically opens and shows that resource's details — even if the panel was previously closed. This means you can close the panel to get more board space, then click any node to bring it back with the right context.
+
+### Connection highlighting
+
+When you select a resource on the board, all of its connections are highlighted in purple. This makes it easy to see at a glance which resources are connected to the selected one, even on a busy board.

package/dist/docs/miro/guides/07-exporting-to-eventcatalog.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 7
+sidebar_label: Exporting to EventCatalog
+title: "Exporting to EventCatalog"
+description: Export your Miro board design back to EventCatalog
+slug: /miro/exporting-to-eventcatalog
+---
+
+Once you've designed your architecture on the Miro board, you can export it and use AI to update your EventCatalog project automatically.
+
+### Exporting the board
+
+1. Open the app panel and navigate to the dashboard
+2. Click the **Export to JSON** button
+3. A `miro-board-export.json` file is downloaded containing all the items currently on your board — cards, sticky notes, connectors, positions, and styles
+
+The export captures everything on the board as raw Miro data, including resources you imported from your catalog and any new resources or connections you created during your design session.
+
+### Updating your catalog with AI
+
+The exported JSON can be used with [EventCatalog Skills](https://github.com/event-catalog/skills) — AI-powered instructions that understand EventCatalog's file structure and conventions. An AI agent can read your Miro board export and update your catalog accordingly.
+
+#### Step 1: Install EventCatalog Skills
+
+If you haven't already, add the EventCatalog skills to your project:
+
+```bash
+npx skills add event-catalog/skills
+```
+
+This installs conversational skills that teach AI agents how to create and update EventCatalog documentation.
+
+#### Step 2: Feed the export to an AI agent
+
+Open your AI agent (e.g. Claude) in your EventCatalog project directory and provide the exported JSON along with instructions. For example:
+
+```
+Here is a Miro board export from our architecture design session.
+Please update my EventCatalog to reflect the changes we made:
+
+- Add any new services, events, commands, or other resources
+- Update connections between services and messages
+- Create documentation files for new resources
+
+<paste or attach miro-board-export.json>
+```
+
+The AI agent will use the EventCatalog skills to:
+
+- Parse the board items and connectors from the Miro export
+- Identify new resources that need to be added to your catalog
+- Identify updated connections between existing resources
+- Generate properly formatted documentation files with correct frontmatter and folder structure
+- Cross-reference existing catalog resources to avoid duplicates
+
+#### Step 3: Review and commit
+
+The AI generates files in your EventCatalog project. Review the changes, then commit them to your repository:
+
+```bash
+git add .
+git commit -m "Update architecture from Miro design session"
+```
+
+### The workflow
+
+The Miro app is designed to fit into a collaborative design workflow:
+
+1. **Import** your existing architecture from EventCatalog into Miro
+2. **Design** collaboratively — add new resources, draw connections, model what comes next
+3. **Export** the board to JSON
+4. **Update** your catalog using AI skills that understand the Miro export format
+5. **Review and merge** — treat architecture changes like code changes with pull requests
+
+This creates a loop where your catalog stays in sync with your team's design decisions, and every change is tracked in version control.

package/dist/docs/miro/guides/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Miro App Guides",
+    "description": "Learn how to use the EventCatalog Miro app to visualize and manage your architecture"
+  }
+}

package/dist/docs/miro/specifications/01-asyncapi.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 1
+sidebar_label: AsyncAPI
+title: "Import AsyncAPI into Miro"
+description: Import your AsyncAPI specifications into Miro via EventCatalog
+slug: /miro/asyncapi
+---
+
+If you have AsyncAPI specifications, you can import them into Miro through EventCatalog. The [AsyncAPI plugin](/docs/plugins/asyncapi/intro) generates services, messages, and channels from your specs — which you can then drag onto a Miro board to visualize and design with your team.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[AsyncAPI Spec] --> B[EventCatalog<br/>AsyncAPI Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **AsyncAPI Spec** — your existing AsyncAPI specification files (YAML or JSON)
+2. **EventCatalog AsyncAPI Plugin** — parses your specs and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services, events, commands, queries, and channels from your specs
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board
+
+### What gets generated
+
+The AsyncAPI plugin creates the following resources from your specifications:
+
+- **Services** — each AsyncAPI spec maps to a service
+- **Messages** — operations become events, commands, or queries (configurable via extensions)
+- **Channels** — AsyncAPI channels are mapped to EventCatalog channels with routing information
+- **Schemas** — message payloads are preserved as schemas in your catalog
+
+All relationships between services, messages, and channels are maintained — so when you drag a service onto the Miro board with dependencies enabled, you'll see the full message flow.
+
+### Getting started
+
+#### 1. Install the AsyncAPI plugin
+
+```bash
+npm install @eventcatalog/generator-asyncapi
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { id: 'my-service', path: './asyncapi.yml' },
+      ],
+      domain: { id: 'my-domain', name: 'My Domain', version: '1.0.0' },
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog).
+
+### Learn more
+
+For full plugin configuration, features, and extensions, see the [AsyncAPI plugin documentation](/docs/plugins/asyncapi/intro).

package/dist/docs/miro/specifications/02-openapi.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 2
+sidebar_label: OpenAPI
+title: "Import OpenAPI into Miro"
+description: Import your OpenAPI specifications into Miro via EventCatalog
+slug: /miro/openapi
+---
+
+If you have OpenAPI specifications, you can import them into Miro through EventCatalog. The [OpenAPI plugin](/docs/plugins/openapi/intro) generates services and messages from your specs — which you can then drag onto a Miro board to visualize and design with your team.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[OpenAPI Spec] --> B[EventCatalog<br/>OpenAPI Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **OpenAPI Spec** — your existing OpenAPI specification files (YAML or JSON)
+2. **EventCatalog OpenAPI Plugin** — parses your specs and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services and messages from your API definitions
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board
+
+### What gets generated
+
+The OpenAPI plugin creates the following resources from your specifications:
+
+- **Services** — each OpenAPI spec maps to a service (or multiple specs can map to one service)
+- **Messages** — API operations become events, commands, or queries based on HTTP method (configurable)
+- **Schemas** — request/response schemas are preserved in your catalog
+- **Consumer services** — optionally define which services consume specific API routes
+
+All relationships between services and messages are maintained — so when you drag a service onto the Miro board with dependencies enabled, you'll see the full API flow.
+
+### Getting started
+
+#### 1. Install the OpenAPI plugin
+
+```bash
+npm install @eventcatalog/generator-openapi
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { id: 'my-api', path: './openapi.yml' },
+      ],
+      domain: { id: 'my-domain', name: 'My Domain', version: '1.0.0' },
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog).
+
+### Learn more
+
+For full plugin configuration, features, and extensions, see the [OpenAPI plugin documentation](/docs/plugins/openapi/intro).

package/dist/docs/miro/specifications/03-schema-registries.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 3
+sidebar_label: Schema Registries
+title: "Import from Schema Registries"
+description: Import schemas from your registry into Miro via EventCatalog
+slug: /miro/schema-registries
+---
+
+If your organization uses a schema registry, you can import your schemas into EventCatalog and use them in Miro. EventCatalog supports several popular schema registries out of the box — and you can build your own using the SDK.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[Schema Registry] --> B[EventCatalog<br/>Registry Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **Schema Registry** — your existing registry containing message schemas
+2. **EventCatalog Registry Plugin** — connects to your registry and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services, messages, and schemas from your registry
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board to model your architecture
+
+### Supported registries
+
+EventCatalog has plugins for the following schema registries:
+
+| Registry | Plugin | Description |
+|----------|--------|-------------|
+| [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) | `@eventcatalog/generator-confluent-schema-registry` | Import Avro, JSON Schema, and Protobuf schemas from Confluent |
+| [AWS Glue Schema Registry](/docs/plugins/aws-glue-registry/intro) | `@eventcatalog/generator-aws-glue-schema-registry` | Import schemas from AWS Glue |
+| [Amazon EventBridge](/integrations/amazon-eventbridge) | `@eventcatalog/generator-amazon-eventbridge` | Import event schemas from EventBridge Schema Registry |
+| [Apicurio Registry](/integrations/apicurio) | `@eventcatalog/generator-apicurio` | Import schemas from Apicurio Registry |
+| [Azure Schema Registry](/docs/plugins/azure-schema-registry/intro) | `@eventcatalog/generator-azure-schema-registry` | Import schemas from Azure Schema Registry |
+| [GitHub](/integrations/github) | `@eventcatalog/generator-github` | Use a GitHub repository as a schema registry |
+
+### Custom registries
+
+If your registry isn't listed above, you can build your own plugin using the [EventCatalog SDK](/docs/sdk). The SDK gives you full control over how schemas are fetched, parsed, and mapped to EventCatalog resources.
+
+### Getting started
+
+Each registry plugin follows the same pattern:
+
+#### 1. Install the plugin
+
+```bash
+npm install @eventcatalog/generator-<your-registry>
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-<your-registry>',
+    {
+      // Plugin-specific configuration
+      // See the plugin docs for details
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog). Your schemas and messages will be available to drag onto the board, connect to services, and use in your architecture design sessions.

package/dist/docs/miro/specifications/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Import from Specifications",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Import OpenAPI & AsyncAPI into Miro",
+    "description": "Use EventCatalog plugins to import your API specifications and visualize them in Miro"
+  }
+}