@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/development/guides/channels/versioning-and-lifecycle/02-changelog.md

@@ -0,0 +1,56 @@
+---
+keywords:
+    - changelog 
+    - channels
+sidebar_label: Adding a changelog
+title: Service changelogs 
+description: Adding changelogs to your channels
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0" />
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services), [messages](/docs/messages) and [channels](/docs/channels).
+
+When you [version a channel](/docs/development/guides/channels/versioning-and-lifecycle/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that service or versioned service.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your channel (or versioned channel)
+    - example `/channels/{Channel}/changelog.mdx`
+    - versioned example `/channels/{Channel}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/channels/OrdersChannel/changelog.mdx"
+---
+createdAt: 2024-08-01
+badges:
+    - content: New channel created
+      backgroundColor: green
+      textColor: green
+---
+
+### Channel protocol update
+
+The OrdersChannel now accepts messages using kafka.
+
+``` 
+
+Navigate to your change log page for your channel or **click on the Changelog button** on your channel page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your channel and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
+

package/dist/docs/development/guides/channels/versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/channels/versioning-and-lifecycle",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}

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

@@ -0,0 +1,34 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are data stores?
+title: Understanding data stores
+description: What are data resources in EventCatalog?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+In EventCatalog **data stores** (containers) represent data stores that are used in your architecture (e.g. databases, caches, objectStore, searchIndexes, etc).
+
+Using the data store resource in EventCatalog you can define how your [services](/docs/development/guides/services/introduction) read/write to data stores in your architecture, helping your teams understand how your services interact with data in your architecture. You can read more about how to add data stores to services [here](/docs/development/guides/services/adding-to-services/adding-data-stores-to-services).
+
+:::tip Data stores are containers (not docker containers!)
+
+Rather than create a new `data` resource directly, we choose to call these `containers`. 
+
+This follows the C4 naming convention for containers (not docker containers!) in your architecture. To learn more about containers you can read the [c4 model](https://c4model.com/abstractions/container).
+
+**For now we only use the data store from c4 model.**
+
+:::
+
+
+<!-- 
+### Further reading
+- [Event-driven architecture and domain-driven design](https://eda-visuals.boyney.io/visuals/eda-and-ddd)
+- [Domain, Subdomain, Bounded Context: Problem/Solution Space in DDD: Clearly Defined](https://medium.com/nick-tune-tech-strategy-blog/domains-subdomain-problem-solution-space-in-ddd-clearly-defined-e0b49c7b586c)
+- [Building Blocks of DDD](https://redis.io/glossary/domain-driven-design-ddd/) -->

package/dist/docs/development/guides/data/02-adding-data.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating a data store  
+title: Creating data stores
+description: Creating and managing services within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+Data stores live in a `/containers` folder. This folder can be placed anywhere in your catalog.
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a data store markdown file may look like._
+
+```md title="/containers/OrdersDatabase/index.mdx (example)"
+---
+# id of your data store, used for slugs and references in EventCatalog.
+id: orders-db
+# Display name of the data store, rendered in EventCatalog.
+name: Orders DB
+# Version of the data store
+version: 0.0.1
+# Type of the data store (e.g. database, cache, objectStore, searchIndex)
+container_type: database
+# Technology of the data store (e.g. postgres@14, redis@7, etc)
+technology: postgres@14
+# Classification of the data store (e.g. internal, external, etc)
+classification: internal
+# Retention of the data store (e.g. 7y, 10y, etc)
+retention: 7y
+# Residency of the data store (e.g. eu-west-1, us-east-1, etc)
+residency: eu-west-1
+---
+
+## Overview
+
+This orders database stores all orders and order lines for the orders domain.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the event will automatically appear across EventCatalog.
+
+## Writing data store content
+
+You can write any Markdown inside a data store.
+
+Each data store gets its own page, so use this space to fully explain how it works.
+
+You can also use [interactive components](/docs/development/components/using-components) to enrich your documentation.
+
+## Assign read/write relationships to data stores
+
+You can assign read/write relationships to data stores in EventCatalog. You can read more about how to do this [here](/docs/development/guides/services/adding-to-services/adding-data-stores-to-services).
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the data store. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/containers/OrdersDatabase/index.mdx (example)"
+---
+id: orders-db
+name: Orders DB
+version: 0.0.1
+container_type: database
+technology: postgres@14
+styles:
+  icon: /icons/database/postgresql.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/database/postgresql.svg`) or an absolute URL. Drop SVG, PNG, or WEBP files into your catalog's `public/` folder and reference them by path.
+
+### What do data stores look like in EventCatalog?
+
+![Example](../img/containers/data-example.png)
+
+_You can see an example of a data store in the [EventCatalog demo](https://demo.eventcatalog.dev/docs/containers/order-metadata-store/0.0.1)._

package/dist/docs/development/guides/data/03a-adding-schemas-to-data-stores.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Adding schemas to data stores
+title: Adding schemas to data stores
+description: Adding schemas to data stores
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+EventCatalog supports any schema format.
+
+When you document your data stores, you may want to also include schemas, queries, or other files that are relevant to your data store.
+
+You can attach this information in two ways:
+
+- [Use codeblocks to render your schema](#using-codeblocks-to-render-your-schema)
+- [Use the `<Schema/>` component to render your schema from a file](#using-the-schema-component-to-render-your-schema-from-a-file)
+
+## Using codeblocks to render your schema
+
+You can use codeblocks to render your schema in your markdown files.
+
+Here is an example of a SQL codeblock:
+
+```md
+```sql
+  CREATE TABLE users (
+    id INT PRIMARY KEY,
+    name VARCHAR(255),
+    email VARCHAR(255)
+  );
+```_
+```
+
+You can learn more about codeblocks and configuring them in the [codeblocks documentation](/docs/api/code-blocks).
+
+## Using the `<Schema/>` component to render your schema from a file
+
+If you prefer to have your schemas, or information about your data store in a file, you can use the `<Schema/>` component to render your schema from a file.
+
+First you need to add your file in the directory of your data store
+
+Example
+
+- `/containers/OrdersDatabase/schema.sql`
+- `/containers/OrdersDatabase/queries.sql`
+
+```md
+<!-- Render the file into your page -->
+<Schema file="schema.sql" lang="sql" title="Users Table" />
+
+<!-- Render the schemas separately in an AccordionGroup -->
+<AccordionGroup>
+  <Accordion title="Users Table">
+    <!-- Load the schema from the file -->
+    <Schema file="schema.sql" lang="sql" title="Users Table" />
+  </Accordion>
+  <Accordion title="Common Queries">
+    <!-- Load the queries from the file -->
+    <Schema file="queries.sql" lang="sql" title="Common Queries" />
+  </Accordion>
+</AccordionGroup>
+```
+
+You can an example of this in the [EventCatalog Demo](https://demo.eventcatalog.dev/docs/containers/orders-db/0.0.1).
+
+:::tip Versioning information
+Remember everything in EventCatalog can be versioned. So when your data store changes you can [version your data stores](/docs/development/guides/data/versioning-and-lifecycle/versioning), and write [changes logs](/docs/development/guides/data/versioning-and-lifecycle/changelog) to help your teams understand what has changed.
+:::

package/dist/docs/development/guides/data/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Data Stores",
+  "position": 11,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/data",
+    "description": "A collection of guides to help you understand data resources and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/data/ownership-and-components/01-owners.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_label: Owners
+title: Adding data store owners
+description: Adding owners to data stores with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the data store.
+
+## Adding owners using frontmatter
+
+To add owners within a data store you need to add them to the `owners` array within your data store frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/services/OrderService/containers/OrderDatabase/index.mdx (example)"
+---
+id: OrderDatabase
+... # other data store frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your data stores can provide others with context of who owns this data store and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can [read the documentation to get started](/docs/owners).
+:::
+
+

package/dist/docs/development/guides/data/ownership-and-components/02-components.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 8
+keywords:
+    - components 
+    - data stores
+sidebar_label: Components
+title: Components
+description: Component list for data stores 
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+You can add custom EventCatalog components to your data stores.
+
+[See the list of components and how to use them](/docs/development/components/using-components).

package/dist/docs/development/guides/data/ownership-and-components/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Ownership & components",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/data/ownership-and-components",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/data/versioning-and-lifecycle/01-versioning.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+keywords:
+- versioning
+- services
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version data stores
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
+
+## How to version a data store
+
+1. Create a `/versioned` directory inside the `/containers` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/containers/OrdersDatabase/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/containers/OrdersDatabase/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the data store.
+    - Example `/containers/OrdersDatabase/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/containers/OrdersDatabase/1.0.2 would load the 1.0.2 version of this data store).
+
+![Example](../../img/domains/versioned-data-store.png)

package/dist/docs/development/guides/data/versioning-and-lifecycle/02-changelog.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 7
+keywords:
+    - changelog 
+    - data stores
+sidebar_label: Adding a changelog
+title: Data store changelogs 
+description: Adding changelogs to your data stores
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services), [messages](/docs/messages) and [data stores](/docs/data).
+
+When you [version a data store](/docs/development/guides/data/versioning-and-lifecycle/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that data store or versioned data store.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your data store (or versioned data store)
+    - example `/services/{Service Name}/containers/{DataStore}/changelog.mdx`
+    - versioned example `/services/{Service Name}/containers/{DataStore}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/services/PaymentService/containers/PaymentDatabase/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: New table added
+      backgroundColor: green
+      textColor: green
+---
+
+### New Table added to the PaymentDatabase
+
+The PaymentDatabase now has a new table called `PaymentTransactions`.
+
+<!-- Other details about the change here -->
+
+``` 
+
+Navigate to your change log page for your data store (example [/docs/services/PaymentService/containers/PaymentDatabase/0.0.1/changelog](https://demo.eventcatalog.dev/docs/services/PaymentService/containers/PaymentDatabase/0.0.1/changelog)) or **click on the Changelog button** on your data store page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your data store and also be used for auditing purposes.
+
+
+

package/dist/docs/development/guides/data/versioning-and-lifecycle/03-deprecating.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_label: Deprecating data stores  
+title: Deprecating data stores
+description: Deprecating data stores with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+Any resource in EventCatalog can be deprecated or marked as deprecated.
+
+This will show a banner on the page indicating that the resource is deprecated.
+
+## Deprecating data stores using frontmatter
+
+To deprecate a data store you need to add the `deprecated` field to the data store frontmatter API.
+
+This accepts a `boolean` or an `object` with the following properties:
+
+- `date`: Date the service will be or was deprecated (YYYY-MM-DD)
+- `message`: Reason the service is deprecated, supports markdown (optional)
+
+```md title="/services/OrderService/containers/OrderDatabase/index.mdx (example)"
+---
+id: OrderDatabase
+... # other data store frontmatter
+
+# deprecated as an object (Recommended)
+deprecated:
+  # Date the data store will be or was deprecated (YYYY-MM-DD)
+  date: 2025-01-01
+  # Reason the data store is deprecated, supports markdown (optional)
+  message: | 
+    This data store has been deprecated and replaced by the new data store **OrderDatabaseV2**.
+    Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+
+# deprecated as a boolean 
+deprecated: true
+---
+
+```
+
+Configuration:
+
+- `deprecated`: `boolean` or `object`
+
+Deprecated as an object is recommended, as it gives your users more information to why the resource is deprecated and a date in the past or future.
+
+- `deprecated.date`: Date the data store will be or was deprecated (YYYY-MM-DD)
+- `deprecated.message`: Reason the data store is deprecated, supports markdown (optional)
+
+
+#### Rendered output
+
+Example of resource that will be deprecated:
+
+![Deprecating services](../../img/deprecated/will-be-deprecated-data-store.png) 
+
+Example of resource that is deprecated:
+
+![Deprecating services](../../img/deprecated/is-deprecated-data-store.png) 
+
+#### Demo
+
+You can see a demo of deprecating resources in the [EventCatalog demo site](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).

package/dist/docs/development/guides/data/versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/data/versioning-and-lifecycle",
+    "description": "A collection of guides to help you understand data versioning and lifecycle in EventCatalog."
+  }
+}

package/dist/docs/development/guides/data-products/01-introduction.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog data products
+- Data products
+sidebar_label: What are data products?
+title: Understanding data products
+description: Data as a product for analytics and insights
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+:::warning Beta Feature
+
+Data Products are currently in **beta** and accepting feedback. The feature and API may change based on community input. Please share your feedback and use cases to help shape the final design.
+
+:::
+
+Data products in EventCatalog represent analytical datasets that transform raw operational (e.g databases, messages, channels) data into high-quality, discoverable, and reusable information assets.
+
+A data product may consumes inputs (e.g [events](/docs/development/guides/messages/events/introduction), [services](/docs/development/guides/services/introduction), [data stores](/docs/development/guides/data/introduction)) and produces outputs (e.g [data stores](/docs/development/guides/data/introduction), metrics) optimized for specific use cases like reporting, business intelligence, or machine learning.
+
+:::tip Data products are first-class resources
+
+Data products have full support in EventCatalog including visualization, schema contracts, versioning, ownership, and relationships with other resources.
+
+You can read more about data products from thoughtworks [here](https://www.thoughtworks.com/en-us/insights/decoder/d/data-product).
+
+:::
+
+## Key characteristics
+
+Data products have specific properties that make them distinct:
+
+**Inputs** (input ports) represent source dependencies including events, services, channels, or data stores that feed the data product.
+
+**Outputs** (output ports) represent the analytical assets produced including aggregated tables, metrics streams, or downstream systems that consume the data.
+
+**Contracts** (data contracts) define the schema structure for output datasets. EventCatalog supports any format (e.g JSON Schema, ODCS YAML).
+
+**Ownership** assigns clear accountability with designated teams or individuals responsible for data quality and availability.
+
+## Use cases
+
+Data products are valuable when you need to:
+
+- Document analytical pipelines and their dependencies
+- Provide and visualize lineage between data products and their inputs and outputs
+- Provide clear contracts for downstream consumers
+- Provide clear SLA's and quality metrics for analytical datasets
+- Enable self-service data discovery and consumption across teams
+
+## Example scenarios
+
+### Order Analytics
+
+Consumes order and payment events to produce aggregated sales metrics, daily revenue summaries, and customer behavior analysis.
+
+```mermaid
+graph LR
+    A["Order Events"] --> B["Order Analytics"]
+    C["Payment Events"] --> B
+    B --> D["Sales Metrics"]
+    B --> E["Revenue Summary"]
+    B --> F["Customer Behavior"]
+    style B fill:#4f46e5,color:#fff
+```
+
+### Payment Metrics
+
+Transforms payment lifecycle events into fraud detection insights, success rate analysis, and revenue attribution by channel.
+
+```mermaid
+graph LR
+    A["Payment Created"] --> B["Payment Metrics"]
+    C["Payment Completed"] --> B
+    D["Payment Failed"] --> B
+    B --> E["Fraud Detection"]
+    B --> F["Success Rate"]
+    B --> G["Revenue by Channel"]
+    style B fill:#4f46e5,color:#fff
+```
+
+### Fulfillment KPIs
+
+Combines order, shipment, and delivery events to produce operational metrics like processing times and delivery performance.
+
+```mermaid
+graph LR
+    A["Order Created"] --> B["Fulfillment KPIs"]
+    C["Shipment Dispatched"] --> B
+    D["Delivery Completed"] --> B
+    B --> E["Processing Times"]
+    B --> F["Delivery Performance"]
+    B --> G["Operational Metrics"]
+    style B fill:#4f46e5,color:#fff
+```
+
+## Relationship to other resources
+
+Data products integrate with existing EventCatalog resources:
+
+- **Messages (e.g events) ** can be inputs to data products for real-time processing
+- **Services** can also be inputs to data products if your data product consumed it's API for example.
+- **Data stores** can be both inputs and outputs for data products
+- **Domains** can contain data products as part of their bounded context
+- **Channels (e.g Eventbus, Kafka, RabbitMQ)** can but inputs and outputs to data products
+
+## SDK support
+
+Data products are fully supported in the EventCatalog SDK, enabling programmatic creation and management of data product documentation.
+
+Use the SDK to automate data product documentation as part of your CI/CD pipeline or integrate with external analytics platforms.
+