@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/plugins/azure-schema-registry/04-examples.md

@@ -0,0 +1,378 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog Azure Schema Registry plugin examples
+sidebar_label: Examples
+title: Examples
+description: Examples of the EventCatalog Azure Schema Registry plugin
+---
+
+# Examples
+
+Explore real-world examples of using the Azure Schema Registry plugin with EventCatalog.
+
+## GitHub Examples Repository
+
+All examples are available in the EventCatalog generators repository:
+
+[View Azure Schema Registry Examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry)
+
+## Available Examples
+
+### Basic Example
+
+**Get started quickly with a simple setup**
+
+This example demonstrates:
+- Connecting to Azure Schema Registry
+- Importing schemas from schema groups
+- Assigning schemas to services
+- Basic configuration setup
+
+[View Basic Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/basic) (Coming Soon)
+
+### Message Types Example
+
+**Document events, commands, and queries**
+
+This example demonstrates:
+- Mapping schemas to different message types
+- Events for things that happened
+- Commands for requests to do something
+- Queries for requests for information
+- Clear architectural patterns
+
+[View Message Types Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/message-types) (Coming Soon)
+
+### Multiple Registries Example
+
+**Fetch schemas from multiple Azure Schema Registries**
+
+This example demonstrates:
+- Default registry URL configuration
+- Per-schema registry URL overrides
+- Multi-region deployment patterns
+- Separate registries for different business units
+
+[View Multiple Registries Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/multiple-registries) (Coming Soon)
+
+### Domain-Driven Design Example
+
+**Organize services into domains**
+
+This example demonstrates:
+- Domain configuration
+- Grouping related services
+- Domain visualization
+- Cross-domain dependencies
+
+[View Domain-Driven Design Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/domains) (Coming Soon)
+
+### Custom Schema Names Example
+
+**User-friendly schema names**
+
+This example demonstrates:
+- Using technical schema IDs
+- Providing user-friendly display names
+- Better discoverability for non-technical users
+
+[View Custom Names Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/custom-names) (Coming Soon)
+
+### Service Authentication Example
+
+**Different authentication methods**
+
+This example demonstrates:
+- Azure CLI authentication (local dev)
+- Service Principal authentication (CI/CD)
+- Managed Identity authentication (Azure-hosted)
+- Environment-specific configurations
+
+[View Authentication Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/authentication) (Coming Soon)
+
+## Running the Examples
+
+Each example includes:
+
+1. **README.md** - Detailed instructions for running the example
+2. **eventcatalog.config.js** - Complete configuration
+3. **.env.example** - Template for environment variables
+4. **Sample data** - Mock schemas and configurations for testing
+
+### Prerequisites
+
+- Node.js 18 or higher
+- Azure CLI installed ([Install guide](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli))
+- Azure account with Event Hubs namespace
+- Azure Schema Registry with sample schemas
+- EventCatalog license key ([14-day trial available](https://eventcatalog.cloud))
+- Appropriate Azure permissions (`Azure Event Hubs Data Receiver` role)
+
+### Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/event-catalog/generators.git
+
+# Navigate to an example
+cd generators/examples/generator-azure-schema-registry/basic
+
+# Install dependencies
+npm install
+
+# Copy and configure environment variables
+cp .env.example .env
+# Edit .env with your EventCatalog license key
+
+# Authenticate with Azure
+az login
+
+# Get Azure access token and set it as environment variable
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Verify token is set
+echo $AZURE_SCHEMA_REGISTRY_TOKEN
+
+# Run the generator
+npm run generate
+
+# Start the catalog
+npm run dev
+```
+
+:::tip One-Line Command
+You can also set the token and run the generator in one command:
+```bash
+AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv) npm run generate
+```
+:::
+
+:::warning Token Expiration
+Azure access tokens expire after 1 hour. If you get authentication errors, refresh your token by running the `export AZURE_SCHEMA_REGISTRY_TOKEN=...` command again.
+:::
+
+## Example Patterns
+
+### Pattern 1: Single Service, Multiple Messages
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+        { id: 'order-updated', schemaGroup: 'com.example.orders' },
+        { id: 'order-cancelled', schemaGroup: 'com.example.orders' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document a single service that produces multiple related events.
+
+### Pattern 2: Multiple Services, Shared Messages
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+    {
+      id: 'inventory-service',
+      version: '1.0.0',
+      receives: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+    {
+      id: 'notifications-service',
+      version: '1.0.0',
+      receives: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document multiple services that consume the same event.
+
+### Pattern 3: Command-Query Separation
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-api',
+      version: '1.0.0',
+      sends: [
+        { id: 'create-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+        { id: 'update-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+      ],
+      receives: [
+        { id: 'get-order', schemaGroup: 'com.example.orders', messageType: 'query' },
+        { id: 'list-orders', schemaGroup: 'com.example.orders', messageType: 'query' },
+      ],
+    },
+    {
+      id: 'orders-processor',
+      version: '1.0.0',
+      receives: [
+        { id: 'create-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+        { id: 'update-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+      ],
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders', messageType: 'event' },
+        { id: 'order-updated', schemaGroup: 'com.example.orders', messageType: 'event' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Implement CQRS pattern with clear separation of commands and queries.
+
+### Pattern 4: Multi-Domain Architecture
+
+```js
+generators: [
+  // Orders Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        { id: 'orders-service', version: '1.0.0', /* ... */ },
+        { id: 'inventory-service', version: '1.0.0', /* ... */ },
+      ],
+    },
+  ],
+  // Payments Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'payments-domain',
+        name: 'Payments Domain',
+        version: '1.0.0',
+      },
+      services: [
+        { id: 'payments-service', version: '1.0.0', /* ... */ },
+      ],
+    },
+  ],
+];
+```
+
+**Use Case**: Organize large architectures into bounded contexts.
+
+### Pattern 5: Multi-Region with Registry Overrides
+
+```js
+{
+  schemaRegistryUrl: 'https://us-east-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'global-orders-service',
+      version: '1.0.0',
+      sends: [
+        {
+          id: 'order-created',
+          schemaGroup: 'com.example.orders',
+          // US East registry
+        },
+        {
+          id: 'order-created-eu',
+          schemaGroup: 'com.example.orders',
+          schemaRegistryUrl: 'https://eu-west-namespace.servicebus.windows.net',
+          // EU West registry
+        },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document multi-region deployments with separate registries.
+
+## Testing Locally
+
+### Using Docker Compose for Local Testing
+
+While Azure Schema Registry requires an Azure account, you can test the plugin configuration locally using mock data:
+
+```bash
+# In the example directory
+npm run generate:mock  # Uses mock schemas for testing
+
+npm run dev  # View the catalog locally
+```
+
+### With Azure Dev/Test Environment
+
+For testing with real Azure Schema Registry:
+
+```bash
+# Step 1: Create a development schema registry (one-time setup)
+az eventhubs namespace create \
+  --name your-dev-namespace \
+  --resource-group your-resource-group \
+  --location eastus \
+  --sku Standard
+
+# Step 2: Register test schemas
+az eventhubs eventhub schema-registry create \
+  --namespace-name your-dev-namespace \
+  --resource-group your-resource-group \
+  --name com.example.test
+
+# Step 3: Get access token
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Step 4: Run the generator
+npm run generate
+
+# Step 5: View the catalog
+npm run dev
+```
+
+:::info Azure Resource Setup
+Make sure you have the appropriate permissions on the Azure resources. You need at least the `Azure Event Hubs Data Receiver` role on the Event Hubs namespace.
+:::
+
+## Contributing Examples
+
+Have a great example you'd like to share? We'd love to include it!
+
+1. Fork the [generators repository](https://github.com/event-catalog/generators)
+2. Create your example in `examples/generator-azure-schema-registry/`
+3. Include a detailed README
+4. Submit a pull request
+
+## Need Help?
+
+Can't find an example for your use case?
+
+- [Ask in Discord](https://eventcatalog.dev/discord)
+- [Open a GitHub Discussion](https://github.com/event-catalog/eventcatalog/discussions)
+- Email: hello@eventcatalog.dev
+
+We're here to help you get the most out of EventCatalog!

package/dist/docs/plugins/azure-schema-registry/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Azure Schema Registry Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "azure-schema-registry",
+    "title": "Azure Schema Registry",
+    "description": "Azure Schema Registry integration for EventCatalog"
+  }
+}

package/dist/docs/plugins/backstage/00-intro.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Backstage plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/mjf7qwoSAC4?si=eBZfgjMOQrD75teb" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+---
+
+Many folks are using [Backstage](https://backstage.spotify.com/) for their internal developer portals. Backstage is a highly configurable platform that allows you to document your architecture in components, apis, services, domains and much more.
+
+Backstage supports plugins, that have a frontend and backend support.
+
+Using the EventCatalog Backstage plugin you can embed your EventCatalog information into backstage.
+
+### Core Features
+
+The EventCatalog Backstage plugin can provide you with many features:
+
+- 📃 Bring [EventCatalog documentation](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3) into Backstage
+- 📃 Custom tabs for your APIs and Services. Embed documentation, visualizations and searchable tables.
+- 📊 Embed [EventCatalog visualizer](https://demo.eventcatalog.dev/visualiser/domains/Orders/0.0.3) into your Backstage pages
+- 🔎 Embed the [EventCatalog discovery table](https://demo.eventcatalog.dev/discover/events) to quickly find messages for your services
+- ⭐ And much more...
+
+### How it works
+
+![Example](/img/integrations/backstage/backstage-eventcatalog.png)
+
+This plugin exposes React components that you can embed on your pages to display information from EventCatalog.
+
+_Your EventCatalog has be hosted and the URL given to the app.config.yml file._
+
+- `<EventCatalogDocumentationEntityPage page="docs/page/visualiser"  />`
+  - Used to embed whole pages of EventCatalog into your Backstage instance. You can add these as tabs to your pages, clicking on the tab will show the desired feature.
+- `<EventCatalogEntityVisualiserCard />`
+  - Used to embed a widget (Card) on your existing pages. This component will display the visualiser on your page.
+- `<EventCatalogEntityMessageCard />`
+  - Used to embed a widget (Card) on your existing pages. This component will display the explore (table) on your page. Great for displaying a list of messages your service produces/consumes.
+
+_Note: If you want to embed private EventCatalog instances, raise an issue on GitHub and we can explore this_.
+
+---
+
+## Commercial Use
+
+This plugin requires a license key to be used. 
+
+You can get a 14 day trial license key to try the plugin out by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You can try the Backstage plugin, or use EventCatalog Scale (as it's already included).
+
+After the trial you can purchase a license to continue using this plugin, we have different plans to suit your organization. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+

package/dist/docs/plugins/backstage/01-installation.md

@@ -0,0 +1,250 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Installation
+title: Installation
+description: Installation instructions for the EventCatalog Backstage plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+:::info Using Backstage plugin version 1.0.0?
+
+We introduced some breaking changes in the plugin, and the ways you map your resources to EventCatalog resources.
+
+We recommend using the latest version of the plugin. You can read the [migration guide](#migrating-from--100-to-100) to help you upgrade.
+
+:::
+
+---
+
+## Configuring EventCatalog for Backstage
+
+You will need a license key to use the backstage integration, this is either the SCALE license key or the Backstage license key.
+
+You can get a 14 day trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+Once you have a license key for Backstage, you will need to build and deploy your EventCatalog with the license key set.
+
+#### 1. Setting license key in `.env` file (recommended)
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+# If you have a Backstage license key
+EVENTCATALOG_LICENSE_KEY_BACKSTAGE=your-license-key
+
+# If you have a SCALE license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an older version of EventCatalog?
+
+If you are using an older version of EventCatalog that does not support the `.env` file, you can just export the license key as an environment variable.
+
+```bash title="Setting license key in environment variables"
+# If you have a Backstage license key
+export EVENTCATALOG_LICENSE_KEY_BACKSTAGE=your-license-key
+
+# If you have a SCALE license key
+export EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::
+
+This will enable you to use EventCatalog within backstage.
+
+## Configuring Backstage to use EventCatalog
+
+### 1. Install the plugin on Backstage
+
+First install the plugin in your Backstage instance.
+
+```sh
+yarn add @eventcatalog/backstage-plugin-eventcatalog
+```
+
+### 2. Add the EventCatalog URL to the app-config.yaml
+
+The EventCatalog plugin needs to know the URL of your EventCatalog instance. This can be set in the `app-config.yaml` file.
+
+```yaml
+eventcatalog:
+  URL: "https://demo.eventcatalog.dev"
+```
+
+### 3. Mapping Backstage resources to EventCatalog resources with annotations
+
+Backstage and EventCatalog have different ways to create resources. For example backstage supports components, APIS, domains, systems etc, and EventCatalog supports resources (domains, services and messages (queries, commands and events)).
+
+When you configure the plugin you need to map Backstage information to EventCatalog information, so the plugin knows which EventCatalog page to render.
+
+We do this by adding annotations to the Backstage resources.
+
+<!-- Make table -->
+
+| Annotation | Required | Default | Description |
+|------------|----------|---------|-------------|
+| `eventcatalog.dev/id` | Yes | - | The id of the resource in EventCatalog |
+| `eventcatalog.dev/version` | No | `latest` | The version of the resource in EventCatalog |
+| `eventcatalog.dev/collection` | No | Uses the entity kind | The collection of the resource in EventCatalog. Options include `services`, `domains`, `queries`, `commands`, `events` |
+
+Example of creating a new service in Backstage and mapping it to an EventCatalog resource:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backend-service
+  description: Backend API service
+  annotations:
+    github.com/project-slug: organization/backend-repo
+    # Here we map the Backstage service to an EventCatalog resource
+    # The id of the resource in EventCatalog
+    eventcatalog.dev/id: InventoryService
+    # The version of the resource in EventCatalog
+    eventcatalog.dev/version: 0.0.2
+    # The collection of the resource in EventCatalog
+    eventcatalog.dev/collection: services
+  tags:
+    - nodejs
+    - express
+    - api
+spec:
+  type: service
+  lifecycle: production
+  owner: team-name
+  system: example-system
+  providesApis:
+    - backend-api
+  dependsOn:
+    - resource:default/database
+```
+
+### 4. Using the components in Backstage
+
+You have two options to use the components in Backstage:
+
+- [Embed EventCatalog as a tabbed page](#tabbed-pages)
+- [Embed EventCatalog as a card component](#card-components)
+
+#### Tabbed pages
+
+The `EventCatalogDocumentationEntityPage` components, is a full page component that you can assign to any `EntityLayout.Route`. 
+
+```js
+import { EventCatalogDocumentationEntityPage } from "@eventcatalog/backstage-plugin-eventcatalog";
+```
+
+You can import the `EventCatalogDocumentationEntityPage` component to render EventCatalog pages as full pages in your Backstage entity.
+
+**Rendered output example:**
+
+![EventCatalog Pages](/img/integrations/backstage/eventcatalog-pages.png)
+
+**Usage Example:**
+
+```js
+// Will create a new tab called "Docs" and route called /eventcatalog. This will embed the docs for that
+// entity in your page. Using the info from the app-config to map your Backstage ID to EventCatalog ID
+<EntityLayout.Route path="/eventcatlaog" title="Docs">
+  <EventCatalogDocumentationEntityPage page='docs' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Visualzer" and route called /eventcatalog-visualizer.
+// This will embed the EventCatalog visualiser to your Backstage entity
+<EntityLayout.Route path="/eventcatlaog-visualizer" title="Visualzer">
+  <EventCatalogDocumentationEntityPage page='visualiser' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Entity Map" and route called /eventcatalog-entity-map.
+// This will embed the EventCatalog entity map to your Backstage entity
+<EntityLayout.Route path="/eventcatlaog-entity-map" title="Entity Map">
+  <EventCatalogDocumentationEntityPage page='entity-map' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Schema Explorer" and route called /eventcatalog-schema-explorer.
+<EntityLayout.Route path="/eventcatlaog-schema-explorer" title="Schema Explorer">
+  <EventCatalogDocumentationEntityPage page='schema-explorer' />
+</EntityLayout.Route>
+
+// Override the id, collection and version of the resource in EventCatalog
+// you can choose to override what is rendered, (not read from your backstage configuration)
+<EntityLayout.Route path="/eventcatlaog-entity-map" title="Entity Map">
+  <EventCatalogDocumentationEntityPage page='entity-map' id="MyDomainId" collection="domains" version="0.0.1" />
+</EntityLayout.Route>
+
+```
+
+#### Card components
+
+These components can be added to your pages as Cards, that can live inside the Backstage Grid System.
+
+![EventCatalog Card Components](/img/integrations/backstage/eventcatalog-card-components.png)
+![EventCatalog Card Components](/img/integrations/backstage/eventcatalog-card-component-entitymap.png)
+
+```jsx
+import {
+  EventCatalogEntityVisualiserCard,
+  EventCatalogEntityMessageCard,
+} from "@eventcatalog/backstage-plugin-eventcatalog";
+
+<Grid container spacing={3} alignItems="stretch">
+  <Grid item md={6}>
+    <!-- Backstage card -->
+    <EntityAboutCard variant="gridItem" />
+  </Grid>
+  <Grid item md={6}>
+    <!-- Adds the visualizer to a grid item in Backstage -->
+    <EventCatalogEntityVisualiserCard />
+  </Grid>
+  <Grid item md={6} xs={12}>
+    <!-- Adds the explore (messages) to a grid item in Backstage -->
+    <EventCatalogEntityMessageCard />
+  </Grid>
+  <Grid item md={6} xs={12}>
+    <!-- Adds the entity map to a grid item in Backstage -->
+    <EventCatalogEntityEntityMapCard />
+  </Grid>
+</Grid>;
+```
+
+---
+
+## Migrating from < 1.0.0
+
+We introduced some breaking changes in the plugin, and the ways you map your resources to EventCatalog resources.
+
+Previously you mapped your resources to EventCatalog resources in the `app-config.yaml` file.
+
+```yaml
+eventcatalog:
+  services:
+    - backstage-name: "backend-service"
+      eventcatalog-id: "InventoryService"
+```
+
+Now you have to use annotations to map your resources to EventCatalog resources.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backend-service
+  annotations:
+    eventcatalog.dev/id: "InventoryService"
+    eventcatalog.dev/version: "0.0.2"
+    eventcatalog.dev/collection: "services"
+```
+
+This are the preferred ways to map your resources to EventCatalog resources and following Backstage best practices.
+
+## Demo
+
+If you want to learn how the code works in a basic demo [you can see our demo on GitHub](https://github.com/event-catalog/backstage-eventcatalog-demo).