@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/resources/services/08-reference.md

@@ -0,0 +1,295 @@
+---
+sidebar_position: 8
+keywords:
+- EventCatalog services
+- Service frontmatter
+sidebar_label: Reference
+title: Services reference
+description: Frontmatter fields, paths, and routes for services in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by services.
+
+## Paths
+
+Services can be created at the root of your catalog:
+
+```txt
+/services/{Service Name}/index.mdx
+```
+
+Services can also be created inside domains or systems:
+
+```txt
+/domains/{Domain Name}/services/{Service Name}/index.mdx
+/systems/{System Name}/services/{Service Name}/index.mdx
+/domains/{Domain Name}/systems/{System Name}/services/{Service Name}/index.mdx
+```
+
+Versioned services use:
+
+```txt
+/services/{Service Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/services/{service-id}/{version}` | Service documentation page. |
+| `/visualiser/services/{service-id}/{version}` | Service resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the service. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: payment-service
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the service.
+
+```md title="Example"
+---
+name: Payment Service
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the service documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the service does.
+
+```md title="Example"
+---
+summary: Authorizes payments and emits payment lifecycle events.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the service.
+
+```md title="Example"
+---
+owners:
+  - payments-platform
+---
+```
+
+### `sends` {#sends}
+
+- Type: `array`
+
+Messages the service sends or publishes.
+
+```md title="Example"
+---
+sends:
+  - id: PaymentAuthorized
+    version: 1.0.0
+---
+```
+
+### `receives` {#receives}
+
+- Type: `array`
+
+Messages the service receives or consumes.
+
+```md title="Example"
+---
+receives:
+  - id: AuthorizePayment
+    version: 1.0.0
+---
+```
+
+### `entities` {#entities}
+
+- Type: `array`
+
+Entities associated with the service.
+
+```md title="Example"
+---
+entities:
+  - id: payment
+    version: 1.0.0
+---
+```
+
+### `writesTo` {#writesTo}
+
+- Type: `array`
+
+Data stores the service writes to.
+
+```md title="Example"
+---
+writesTo:
+  - id: payments-database
+    version: 1.0.0
+---
+```
+
+### `readsFrom` {#readsFrom}
+
+- Type: `array`
+
+Data stores the service reads from.
+
+```md title="Example"
+---
+readsFrom:
+  - id: customer-database
+    version: 1.0.0
+---
+```
+
+### `flows` {#flows}
+
+- Type: `array`
+
+Flows associated with the service.
+
+```md title="Example"
+---
+flows:
+  - id: payment-authorization
+    version: 1.0.0
+---
+```
+
+### `externalSystem` {#externalSystem}
+
+- Type: `boolean`
+
+Marks the service as an external service or integration.
+
+```md title="Example"
+---
+externalSystem: true
+---
+```
+
+### `specifications` {#specifications}
+
+- Type: `object` or `array`
+
+OpenAPI, AsyncAPI, or GraphQL specifications for the service.
+
+```md title="Example"
+---
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Public API
+  - type: asyncapi
+    path: asyncapi.yml
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the service page.
+
+```md title="Example"
+---
+badges:
+  - content: Critical
+    backgroundColor: red
+    textColor: red
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the service.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/payment-service
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the service.
+
+```md title="Example"
+---
+diagrams:
+  - id: payment-service-sequence
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the service.
+
+```md title="Example"
+---
+attachments:
+  - url: https://runbooks.example.com/payment-service
+    title: Payment Service runbook
+    type: runbook
+---
+```
+
+## Resource pointers
+
+Services reference related resources using `id` and optional `version`.
+
+```md
+---
+sends:
+  - id: OrderCreated
+receives:
+  - id: CreateOrder
+writesTo:
+  - id: orders-database
+flows:
+  - id: checkout-flow
+---
+```
+
+If `version` is omitted, EventCatalog uses the latest version.

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

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

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

@@ -0,0 +1,119 @@
+---
+keywords:
+- EventCatalog domains
+- EventCatalog systems
+sidebar_label: What are systems?
+title: What are systems?
+description: What are systems? Why are they useful in EventCatalog?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="4.0" />
+
+A system is a collection of resources that work together to perform a function.
+
+In EventCatalog, systems help you document software capabilities at a useful operating level. They often sit between domains and the lower-level resources that make up your architecture, but they do not have to belong to a domain.
+
+One way you can think of this:
+
+- **Domains** describe a business boundary or bounded context.
+- **Systems** describe a software capability or external system.
+- **Resources** describe the things that make up, connect to, or document that system.
+
+For example, a `Shopping` domain might contain a `Cart System` and a `Promotion System`. The `Cart System` is made up of resources (e.g cart state, service (API), and publishes events).
+
+## Why use systems?
+
+Systems help teams document architecture at a useful operating level.
+
+Services, messages, containers, flows, and entities are useful on their own, but larger catalogs can become hard to navigate if every resource sits directly inside a domain. Systems give you a way to group the resources that cooperate to deliver one capability.
+
+Use systems when you want to show:
+
+- The boundary of a product capability or technical system.
+- Which services, containers, flows, and entities belong together.
+- Which team owns a system.
+- Which people or roles interact with the system.
+- Which other systems it depends on.
+- Whether the system is internal or external.
+
+## How systems relate to other resources
+
+A system can reference:
+
+- [Services](/docs/development/guides/resources/services/introduction)
+- [Flows](/docs/development/guides/resources/flows/introduction)
+- [Entities](/docs/development/guides/resources/entities/introduction)
+- [Data stores](/docs/development/guides/resources/data/introduction)
+
+Contracts such as schemas, OpenAPI specs, AsyncAPI specs, and GraphQL schemas are documented on the messages and services inside the system. This makes the system the entry point for understanding which contracts it implements, consumes, or produces.
+
+Systems can also define:
+
+- **Relationships** to other systems, such as "calculates discounts via" or "sends notifications to".
+- **Actors**, such as "Shopper", "Support Agent", or "Warehouse Operator".
+- **Scope**, so a system can be marked as `internal` or `external`.
+
+## Systems vs services
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+A system is a higher-level boundary that can contain one or more services plus the supporting resources that make that function work.
+
+For example:
+
+- `Cart System` is the system.
+- `Cart API` is a service inside the system.
+- `cart-database` is a container inside the system.
+- `CartCheckedOut` is an event produced by the system through one of its services.
+
+## Systems vs domains
+
+A domain is a business boundary. A system is how part of that domain is implemented or operated.
+
+One domain can contain many systems. Each system can then contain the resources that belong to that specific capability.
+
+Systems can also live outside domains when they are shared, external, or not owned by one business boundary.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'promotion-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This keeps the business model clear while still giving engineering teams a place to document the concrete systems they own and operate.

package/dist/docs/development/guides/systems/02-create-system.md

@@ -0,0 +1,127 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog systems
+sidebar_label: Create a system
+title: Create a system
+description: Create a system 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';
+
+<AddedIn version="4.0" />
+
+A system is a collection of resources that work together to perform a function.
+
+Use a system when you want to document a group of resources that work together to perform one function.
+
+![Example system page in EventCatalog](./img/create-system-example.png)
+
+## Creating a system
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog system">
+Read https://www.eventcatalog.dev/docs/development/guides/systems/create-system.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/systems.md then help me create a new EventCatalog system in my catalog.
+
+Ask me for the system name, what function it performs, whether it is internal or external, and whether it belongs inside a domain. Then create the correct systems/{'{System Name}'}/index.mdx or domains/{'{Domain Name}'}/systems/{'{System Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+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 system should live, create the right folder structure, and add the first version of the system documentation.
+
+### Manual Creation
+
+Systems can live inside a domain or at the root of your catalog.
+
+If the system clearly belongs to one domain, keep it inside that domain and [attach the domain to that system](/docs/development/guides/domains/add-resources-to-domains/add-systems-to-domains).
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the system is shared, external, or you want to attach it to domains later, create it at the root:
+
+<ProjectTree
+  items={[
+    {
+      name: 'systems',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'stripe',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Most teams start by keeping systems inside the domain they belong to.
+
+## Create the system file
+
+Create an `index.mdx` file for the system.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+# freindly name of the system
+name: Cart System
+version: 1.0.0
+# summary of the system
+summary: |
+  Internal system that owns the customer's shopping cart and checkout flow.
+# is the system internal to your organization or external
+scope: internal
+# who owns this system in your organization?
+owners:
+  - shopping-platform
+---
+
+## Overview
+
+The Cart System owns the shopping cart. It accepts commands to add and remove items, persists cart contents in the cart database, asks the Promotion System to calculate discounts, and publishes an event when a cart is checked out.
+```
+
+## Next steps
+
+- [Add resources to the system](/docs/development/guides/systems/add-resources-to-systems)
+- [Model relationships and actors](/docs/development/guides/systems/model-relationships-and-actors)
+- [Add systems to domains](/docs/development/guides/domains/add-resources-to-domains/add-systems-to-domains)
+- [Visualize systems with context maps](/docs/development/guides/systems/system-context-maps)
+- [Review the systems reference](/docs/development/guides/systems/reference)

package/dist/docs/development/guides/systems/03-add-resources-to-systems.md

@@ -0,0 +1,157 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog systems
+- system resources
+sidebar_label: Add resources to systems
+title: Add resources to systems
+description: Add services, flows, entities, and data stores to systems.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="4.0" />
+
+In EventCatalog, systems can directly reference:
+
+- [Services](/docs/development/guides/resources/services/introduction)
+- [Flows](/docs/development/guides/resources/flows/introduction)
+- [Entities](/docs/development/guides/resources/entities/introduction)
+- [Data stores](/docs/development/guides/resources/data/introduction)
+
+Messages, APIs, schemas, and channels are usually documented through the services and messages inside the system.
+
+## Add resources using frontmatter
+
+Add resources to the system frontmatter using `services`, `flows`, `entities`, and `containers`.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+# define services in this system
+services:
+  - id: cart-api
+    version: 1.0.0
+# define databases in this system    
+containers:
+  - id: cart-database
+    version: 1.0.0
+# define documented business workflows part of this system
+flows:
+  - id: checkout-flow
+    version: 1.0.0
+# define any entities that belong to this system
+entities:
+  - id: cart
+    version: 1.0.0
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced resource.
+
+## Keep resources inside the system folder
+
+You can also define resources inside the system folder to keep related architecture documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'index.mdx', highlight: true },
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'CartAPI',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'containers',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'cart-database',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'flows',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'CheckoutFlow',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure makes the system the entry point for the resources that make up that capability.
+
+## Show the resource diagram
+
+Add `<NodeGraph />` to the system page to show the resources inside the system.
+
+
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+## Resource Diagram
+
+<NodeGraph />
+```
+
+![Product Catalog System resource diagram](./img/product-catalog-system-resource-map.png)
+
+You can also open the resource diagram directly:
+
+```txt
+/visualiser/systems/{system-id}/{version}
+```
+
+For the complete list of supported fields, see the [systems reference](/docs/development/guides/systems/reference).