@eventcatalog/core 4.1.3 → 4.1.4

package/dist/docs/development/guides/resources/agents/11-reference.md

@@ -0,0 +1,238 @@
+---
+keywords:
+- EventCatalog agents
+- Agent frontmatter
+sidebar_position: 11
+sidebar_label: Reference
+title: Agents reference
+description: Frontmatter fields, paths, and routes for agents in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by agents.
+
+## Paths
+
+Agents can be created in any `agents` folder:
+
+```txt
+/agents/{Agent Name}/index.mdx
+/domains/{Domain Name}/agents/{Agent Name}/index.mdx
+```
+
+Versioned agents use:
+
+```txt
+/agents/{Agent Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/agents/{agent-id}/{version}` | Agent documentation page. |
+| `/visualiser/agents/{agent-id}/{version}` | Agent resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the agent. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: customer-support-agent
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the agent.
+
+```md title="Example"
+---
+name: Customer Support Agent
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the agent documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of what the agent does.
+
+```md title="Example"
+---
+summary: Answers customer support questions using catalog and order context.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the agent.
+
+```md title="Example"
+---
+owners:
+  - support-platform
+---
+```
+
+### `model` {#model}
+
+- Type: `object`
+
+Model metadata for the agent.
+
+```md title="Example"
+---
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+  version: "2025-04-14"
+---
+```
+
+### `tools` {#tools}
+
+- Type: `array`
+
+Tools the agent can use.
+
+```md title="Example"
+---
+tools:
+  - name: Order lookup
+    type: mcp
+    url: https://mcp.example.com/orders
+    description: Retrieves order status and recent order events.
+---
+```
+
+### `sends` {#sends}
+
+- Type: `array`
+
+Messages the agent sends.
+
+```md title="Example"
+---
+sends:
+  - id: SupportCaseCreated
+    version: 1.0.0
+---
+```
+
+### `receives` {#receives}
+
+- Type: `array`
+
+Messages the agent receives.
+
+```md title="Example"
+---
+receives:
+  - id: CustomerQuestionAsked
+    version: 1.0.0
+---
+```
+
+### `readsFrom` {#readsFrom}
+
+- Type: `array`
+
+Data stores the agent reads from.
+
+```md title="Example"
+---
+readsFrom:
+  - id: support-knowledge-base
+    version: 1.0.0
+---
+```
+
+### `writesTo` {#writesTo}
+
+- Type: `array`
+
+Data stores the agent writes to.
+
+```md title="Example"
+---
+writesTo:
+  - id: support-case-store
+    version: 1.0.0
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the agent page.
+
+```md title="Example"
+---
+badges:
+  - content: AI
+    backgroundColor: purple
+    textColor: purple
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the agent.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/support-agent
+---
+```
+
+## Model fields
+
+```md
+---
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+  version: "2025-04-14"
+---
+```
+
+## Tool fields
+
+```md
+---
+tools:
+  - name: Order lookup
+    type: mcp
+    url: https://mcp.example.com/orders
+    description: Retrieves order status and recent order events.
+---
+```

package/dist/docs/development/guides/{agents → resources/agents}/_category_.json

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

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

@@ -0,0 +1,15 @@
+---
+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';
+
+In EventCatalog **data stores** represent data stores that are used in your architecture (e.g. databases, caches, object store, search indexes, etc).
+
+Using the data store resource in EventCatalog you can define how your [services](/docs/development/guides/resources/services/introduction) read/write to data stores in your architecture, helping your teams understand how your services interact with data in your architecture. 

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

@@ -0,0 +1,184 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog data stores
+sidebar_label: Create a data store
+title: Create a data store
+description: Creating and managing data stores within 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';
+
+<AddedIn version="2.59.0" />
+
+Data stores document the databases, caches, object stores, search indexes, warehouses, and other storage systems used by your architecture.
+
+![Example](../../img/containers/data-example.png)
+
+## Adding a new data store
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog data store">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/data/adding-data.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/containers.md then help me create a new EventCatalog data store in my catalog.
+
+Ask me for the data store name, what it stores, summary, type, technology, classification, retention, residency, whether it belongs at the root of the catalog or inside a service or system, and any known services or agents that read from or write to it. Then create the correct containers/{'{Data Store Name}'}/index.mdx, services/{'{Service Name}'}/containers/{'{Data Store Name}'}/index.mdx, systems/{'{System Name}'}/containers/{'{Data Store Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/containers/{'{Data Store Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services or systems, put it into the root containers 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 data store should live, create the right folder structure, and add the first version of the data store documentation.
+
+### Manual Creation
+
+Data stores live in a `containers` folder. EventCatalog discovers any `index.mdx` file inside a `containers` directory, regardless of where that directory lives in your catalog.
+
+You can place data stores:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'containers',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrdersDatabase',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a system:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'order-management-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'containers',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'OrdersDatabase',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+## Create the data store file
+
+Create an `index.mdx` file for the data store.
+
+_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 data store will automatically appear across EventCatalog.
+
+### 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 in [Add read/write relationships](/docs/development/guides/resources/data/add-read-write-relationships).

package/dist/docs/development/guides/resources/data/03-add-read-write-relationships.md

@@ -0,0 +1,128 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog data stores
+- readsFrom
+- writesTo
+sidebar_label: Add read/write relationships
+title: Add read/write relationships
+description: Document which resources read from and write to data stores.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Data stores become more useful when EventCatalog knows which resources read from them and write to them.
+
+Use `writesTo` when a resource stores, appends, or updates data in a data store. Use `readsFrom` when a resource reads, queries, or depends on data from a data store.
+
+## How relationships work
+
+Read/write relationships are defined on the resource that uses the data store.
+
+For example, if `OrdersService` writes to `OrdersDatabase` and reads from `ProductRedisCache`, add `writesTo` and `readsFrom` to the service frontmatter.
+
+```md title="/services/OrdersService/index.mdx"
+---
+id: OrdersService
+name: Orders Service
+version: 1.0.0
+
+# Data stores this service writes to
+writesTo:
+  - id: OrdersDatabase
+
+# Data stores this service reads from
+readsFrom:
+  - id: ProductRedisCache
+    # optional version. If omitted, EventCatalog uses the latest version.
+    version: 1.0.0
+---
+```
+
+## Create the data stores
+
+The referenced data stores still need to exist in your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'ProductRedisCache',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+The `id` values in `readsFrom` and `writesTo` must match the `id` fields in the data store frontmatter.
+
+```md title="/containers/OrdersDatabase/index.mdx"
+---
+id: OrdersDatabase
+name: Orders Database
+version: 1.0.0
+container_type: database
+technology: PostgreSQL
+---
+```
+
+```md title="/containers/ProductRedisCache/index.mdx"
+---
+id: ProductRedisCache
+name: Product Redis Cache
+version: 1.0.0
+container_type: cache
+technology: Redis
+---
+```
+
+## Version matching
+
+You can provide a specific version when linking to a data store.
+
+```md
+readsFrom:
+  - id: ProductRedisCache
+    version: 1.0.0
+```
+
+If no version is provided, EventCatalog uses the latest version.
+
+## Visualize the relationships
+
+When a resource reads from or writes to a data store, EventCatalog can show that relationship in the visualiser and on resource pages.
+
+![Service visualiser showing read and write relationships to data stores](../../img/services/visualiser-with-data.png)
+
+## Next steps
+
+You can use the same relationship pattern when connecting data stores to services and agents.
+
+- [Add data stores to services](/docs/development/guides/resources/services/add-resources-to-services/add-data-stores-to-services)
+- [Add data stores to agents](/docs/development/guides/resources/agents/add-data-stores-to-agents)