@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/tutorial/04-add-ownership.md

@@ -0,0 +1,184 @@
+---
+sidebar_position: 7
+sidebar_label: Add ownership
+slug: /tutorial/add-ownership
+title: Add ownership
+description: Create a team and assign it to your services and event.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will add ownership to your catalog.
+
+Ownership helps people understand who maintains a service or event, who to ask for help, and who should review changes.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create the Commerce Platform Team.',
+    },
+    {
+      icon: 'server',
+      text: 'Assign the team to both services.',
+    },
+    {
+      icon: 'network',
+      text: 'Assign the team to OrderPlaced.',
+    },
+  ]}
+/>
+
+### Create the team
+
+Owners in EventCatalog can be [teams](/docs/development/guides/owners/what-are-teams-and-users) or [users](/docs/development/guides/owners/what-are-teams-and-users). For this tutorial, you will create one team: `Commerce Platform Team`.
+
+From the root of your catalog, create a `teams` folder:
+
+```bash
+mkdir -p teams
+```
+
+Create a new file at `teams/commerce-platform-team.mdx`:
+
+```mdx title="teams/commerce-platform-team.mdx"
+---
+id: commerce-platform-team
+name: Commerce Platform Team
+summary: |
+  Owns the services and events that support customer ordering.
+email: commerce-platform@example.com
+---
+
+## Overview
+
+The Commerce Platform Team owns the systems that support customer checkout, ordering, and inventory coordination.
+```
+
+The important frontmatter fields are:
+
+- `id` is the stable identifier you will reference from other resources.
+- `name` is the label people see in EventCatalog.
+- `summary` explains what the team owns.
+- `email` gives people a contact path.
+
+You can learn more in the [teams guide](/docs/development/guides/owners/what-are-teams-and-users).
+
+### Assign the services
+
+Open `services/OrderService/index.mdx` and add `owners` to the frontmatter:
+
+```mdx title="services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: |
+  Handles customer orders from checkout through to fulfilment.
+owners:
+  - commerce-platform-team
+sends:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+Now open `services/InventoryService/index.mdx` and add the same owner:
+
+```mdx title="services/InventoryService/index.mdx"
+---
+id: InventoryService
+name: Inventory Service
+version: 0.0.1
+summary: |
+  Tracks stock levels and reserves inventory for customer orders.
+owners:
+  - commerce-platform-team
+receives:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+The `owners` list references the team `id`, not the display name.
+
+### Assign the event
+
+Open `services/OrderService/events/OrderPlaced/index.mdx` and add the same owner:
+
+```mdx title="services/OrderService/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 0.0.1
+summary: |
+  Raised when a customer places an order.
+owners:
+  - commerce-platform-team
+schemaPath: schema.json
+---
+```
+
+Assigning owners to events is optional, but useful when the event contract needs a clear team responsible for changes.
+
+You can learn more in the [messages reference](/docs/development/guides/resources/messages/reference#owners) and the [service reference](/docs/development/guides/resources/services/reference#owners).
+
+### Check ownership in EventCatalog
+
+Refresh EventCatalog and open [OrderService](http://localhost:3000/docs/services/OrderService/0.0.1).
+
+You should see `Commerce Platform Team` listed as an owner of the service.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-service-owner-page.png"
+    alt="Order Service showing Commerce Platform Team as an owner"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    Order Service shows Commerce Platform Team as the owner.
+  </figcaption>
+</figure>
+
+Open [OrderPlaced](http://localhost:3000/docs/events/OrderPlaced/0.0.1).
+
+You should see the same team listed as the owner of the event. This tells people who maintains the event contract and who to contact before changing it.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-owner-page.png"
+    alt="Order Placed event showing Commerce Platform Team as an owner"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    Order Placed shows its owner alongside its producers and consumers.
+  </figcaption>
+</figure>
+
+Open [Commerce Platform Team](http://localhost:3000/docs/teams/commerce-platform-team) from the team directory.
+
+The team page gives people a central place to understand who owns this part of the architecture.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/commerce-platform-team-page.png"
+    alt="Commerce Platform Team page showing owned services and messages"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The team page lists the services and messages owned by Commerce Platform Team.
+  </figcaption>
+</figure>
+
+### What you have now
+
+Your catalog now has a first ownership model:
+
+- a team page
+- owned services
+- an owned event
+- a clear contact path for the team
+
+### Next
+
+Continue to [Create a domain](/docs/tutorial/create-a-domain).

package/dist/docs/tutorial/04-create-event.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 4
+sidebar_label: Create an event
+slug: /tutorial/create-event
+title: Create an event
+description: Add the first event and schema to your tutorial catalog.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will document the first event in your catalog and add a schema for its payload.
+
+An event describes something that has happened. In this tutorial, the first event is `OrderPlaced`. It tells other systems that a customer has placed an order.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create an event folder inside OrderService.',
+    },
+    {
+      icon: 'file',
+      text: 'Add the event metadata and a short description.',
+    },
+    {
+      icon: 'code',
+      text: 'Add a JSON schema and render it on the event page.',
+    },
+    {
+      icon: 'eye',
+      text: 'Open the event in EventCatalog.',
+    },
+  ]}
+/>
+
+### Create the event folder
+
+From the root of your catalog, create an event folder inside `OrderService`:
+
+```bash
+mkdir -p services/OrderService/events/OrderPlaced
+```
+
+This keeps the event close to the service that publishes it. You can also put events in a top-level `events` folder, but service-owned events are a useful place to start when you are learning.
+
+### Add the event page
+
+Create a new file at `services/OrderService/events/OrderPlaced/index.mdx`:
+
+```mdx title="services/OrderService/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 0.0.1
+summary: |
+  Raised when a customer places an order.
+schemaPath: schema.json
+---
+
+## Overview
+
+The Order Placed event is raised after a customer completes checkout.
+
+Other systems can use this event to start work that depends on the order, such as fulfilment, inventory allocation, or customer notifications.
+
+## Schema
+
+<SchemaViewer file="schema.json" title="OrderPlaced schema" maxHeight="500" search="true" />
+```
+
+Keep the event focused on what happened and why it matters. The important part is the frontmatter at the top of the file:
+
+- `id` is the stable identifier EventCatalog uses for links and references.
+- `name` is the label people see in the UI.
+- `version` is the version of this event.
+- `summary` is a short description shown in event lists and page headers.
+- `schemaPath` tells EventCatalog which schema belongs to this event.
+
+### Add the schema file
+
+The event page explains the meaning of the event. The schema explains the shape of the payload.
+
+EventCatalog supports any schema format. In this tutorial, you will add a JSON schema.
+
+:::info Using a schema registry?
+EventCatalog has [many integrations](https://www.eventcatalog.dev/integrations) and can sync schemas directly from your registry into the catalog. In this tutorial, you will manually create the schema, but you can set up a registry integration later.
+:::
+
+Create `schema.json` in the same folder as the event:
+
+```json title="services/OrderService/events/OrderPlaced/schema.json"
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/order-placed.json",
+  "title": "OrderPlaced",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["eventId", "orderId", "customerId", "total", "currency", "createdAt"],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "description": "Unique identifier for this event."
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Unique identifier for the order."
+    },
+    "customerId": {
+      "type": "string",
+      "description": "Unique identifier for the customer."
+    },
+    "total": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Total value of the order."
+    },
+    "currency": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 3,
+      "description": "Three letter currency code for the order total."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time the order was created."
+    }
+  }
+}
+```
+
+### Show the schema on the event page
+
+The event page already includes the [`SchemaViewer`](/docs/development/components/components/schema-viewer) component:
+
+```mdx
+<SchemaViewer file="schema.json" title="OrderPlaced schema" maxHeight="500" search="true" />
+```
+
+[`SchemaViewer`](/docs/development/components/components/schema-viewer) renders schemas in a more readable way than a plain code block.
+
+### Check the event in EventCatalog
+
+Refresh EventCatalog in your browser. You should now be able to find `OrderPlaced` in your catalog at [http://localhost:3000/docs/events/OrderPlaced/0.0.1](http://localhost:3000/docs/events/OrderPlaced/0.0.1).
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-event-page.png"
+    alt="The Order Placed event page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Order Placed event page after adding the event and schema.</figcaption>
+</figure>
+
+The schema should also render on the event page.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-schema-viewer.png"
+    alt="The SchemaViewer component rendering the OrderPlaced schema"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The OrderPlaced schema rendered with SchemaViewer.</figcaption>
+</figure>
+
+### What you have now
+
+Your catalog now has:
+
+- `services/OrderService/events/OrderPlaced/index.mdx`
+- `services/OrderService/events/OrderPlaced/schema.json`
+- a [`SchemaViewer`](/docs/development/components/components/schema-viewer) block that renders the schema in EventCatalog
+
+### Next
+
+Continue to [Publish the event from a service](/docs/tutorial/publish-event).

package/dist/docs/tutorial/05-create-a-domain.md

@@ -0,0 +1,133 @@
+---
+sidebar_position: 8
+sidebar_label: Create a domain
+slug: /tutorial/create-a-domain
+title: Create a domain
+description: Group the tutorial services into a domain.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create your first domain.
+
+A [domain](/docs/development/guides/domains/introduction) groups related parts of your architecture around a business area. In this tutorial, you will create an `E-Commerce` domain and add the two services you already created.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create an E-Commerce domain folder.',
+    },
+    {
+      icon: 'server',
+      text: 'Add OrderService and InventoryService to the domain.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and check the domain page.',
+    },
+  ]}
+/>
+
+### Create the domain folder
+
+From the root of your catalog, create a folder for the domain:
+
+```bash
+mkdir -p domains/E-Commerce
+```
+
+### Add the domain page
+
+Create a new file at `domains/E-Commerce/index.mdx`:
+
+```mdx title="domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 0.0.1
+summary: |
+  Contains the services that support customer ordering.
+owners:
+  - commerce-platform-team
+services:
+  - id: OrderService
+    version: 0.0.1
+  - id: InventoryService
+    version: 0.0.1
+---
+
+## Overview
+
+The E-Commerce domain contains the services that support checkout, orders, and inventory coordination.
+```
+
+The important frontmatter fields are:
+
+- `id` is the stable identifier for the domain.
+- `name` is the label people see in EventCatalog.
+- `version` is the version of the domain page.
+- `summary` explains what belongs in the domain.
+- `owners` links the domain to the team that owns it.
+- `services` lists the services that belong to the domain.
+
+You can learn more in the [create a domain guide](/docs/development/guides/domains/create-domain), [add services to domains guide](/docs/development/guides/domains/add-resources-to-domains/add-services-to-domains), and [domain owners guide](/docs/development/guides/domains/ownership-and-language/owners).
+
+The `version` field inside each service reference is optional. If you leave it out, EventCatalog will use the latest version of that service.
+
+### Check the domain in EventCatalog
+
+Refresh EventCatalog in your browser and open the `E-Commerce` domain.
+
+You should see the domain page and the two services listed in the sidebar at [http://localhost:3000/docs/domains/E-Commerce/0.0.1](http://localhost:3000/docs/domains/E-Commerce/0.0.1)
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/e-commerce-domain-page.png"
+    alt="E-Commerce domain page showing Order Service and Inventory Service"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The E-Commerce domain groups Order Service and Inventory Service.
+  </figcaption>
+</figure>
+
+### Check the domain map
+
+Open the `Map` view from the domain page.
+
+EventCatalog shows the services that belong to the domain. Because those services already publish and consume `OrderPlaced`, the map also shows that relationship. You still only added services to the domain.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/e-commerce-domain-map.png"
+    alt="E-Commerce domain map showing Order Service and Inventory Service"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The E-Commerce domain map shows the services in the domain and the event relationship between them.
+  </figcaption>
+</figure>
+
+:::tip Show the domain map on the page
+You can also embed the domain visualization directly into the domain documentation page with the [`NodeGraph`](/docs/development/components/components/nodegraph) component:
+
+```mdx
+<NodeGraph />
+```
+:::
+
+### What you have now
+
+Your catalog now has:
+
+- two services
+- one event
+- a schema
+- producer and consumer relationships
+- ownership
+- an `E-Commerce` domain that groups the services
+
+### Next
+
+Continue to [Visualize your catalog](/docs/tutorial/visualize-your-catalog).

package/dist/docs/tutorial/05-publish-event.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 5
+sidebar_label: Publish from a service
+slug: /tutorial/publish-event
+title: Publish the event from a service
+description: Update OrderService so EventCatalog knows it publishes OrderPlaced.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will connect `OrderService` to the `OrderPlaced` event.
+
+In EventCatalog, a service publishes an event by listing it under `sends`.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'server',
+      text: 'Open the OrderService page.',
+    },
+    {
+      icon: 'network',
+      text: 'Add OrderPlaced to the sends list.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and inspect the relationship.',
+    },
+  ]}
+/>
+
+### Update the service
+
+Open `services/OrderService/index.mdx` and add `sends` to the frontmatter:
+
+```mdx title="services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: |
+  Handles customer orders from checkout through to fulfilment.
+sends:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+Keep the markdown content below the frontmatter as it is.
+
+The `version` field inside `sends` is optional. If you leave it out, EventCatalog will use the latest version of the event.
+
+### Check the relationship
+
+Refresh EventCatalog in your browser and open the [Order Service page](http://localhost:3000/visualiser/services/OrderService/0.0.1).
+
+You should now be able to see that `OrderService` publishes `OrderPlaced`. Open the event page as well. EventCatalog can now show the event and its producer as connected resources.
+
+You can also open the `Map` view from the Order Service page to see the relationship visually.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-service-publishes-order-placed-map.png"
+    alt="The Order Service map showing that it publishes the Order Placed event"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Order Service map showing the OrderPlaced publish relationship.</figcaption>
+</figure>
+
+We are only setting up the producer in this step. Next, you will add another service and connect it as a consumer with `receives`.
+
+### What you have now
+
+Your catalog now knows:
+
+- `OrderPlaced` is an event.
+- `OrderPlaced` has a schema.
+- `OrderService` publishes `OrderPlaced`.
+
+### Next
+
+Continue to [Consume the event from a service](/docs/tutorial/consume-event).

package/dist/docs/tutorial/06-consume-event.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 6
+sidebar_label: Consume from a service
+slug: /tutorial/consume-event
+title: Consume the event from a service
+description: Create InventoryService and mark it as a consumer of OrderPlaced.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create `InventoryService` and connect it to the `OrderPlaced` event.
+
+In EventCatalog, a service consumes an event by listing it under `receives`.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'server',
+      text: 'Create the InventoryService page.',
+    },
+    {
+      icon: 'network',
+      text: 'Add OrderPlaced to the receives list.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and inspect the full relationship.',
+    },
+  ]}
+/>
+
+### Create the service folder
+
+From the root of your catalog, create a new folder for the service:
+
+```bash
+mkdir -p services/InventoryService
+```
+
+### Add the service page
+
+Create a new file at `services/InventoryService/index.mdx` and add `receives` to the frontmatter:
+
+```mdx title="services/InventoryService/index.mdx"
+---
+id: InventoryService
+name: Inventory Service
+version: 0.0.1
+summary: |
+  Tracks stock levels and reserves inventory for customer orders.
+receives:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+
+## Overview
+
+The inventory service tracks product avaliability and reservces stock when a customer places an order.
+
+```
+
+Keep the markdown content below the frontmatter as it is.
+
+The frontmatter follows the same shape as `OrderService`:
+
+- `id` is the stable identifier EventCatalog uses for links and references.
+- `name` is the label people see in the UI.
+- `version` is the version of this service.
+- `summary` appears in service lists and page headers.
+- `receives` lists the events this service consumes.
+
+The `version` field inside `receives` is optional. If you leave it out, EventCatalog will use the latest version of the event.
+
+### Check the service in EventCatalog
+
+Refresh EventCatalog in your browser. You should now be able to find `InventoryService` in your catalog.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/inventory-service-page.png"
+    alt="The Inventory Service page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Inventory Service page after adding the service file.</figcaption>
+</figure>
+
+### Check the relationship
+
+Refresh EventCatalog in your browser and open the `OrderPlaced` event page.
+
+You should now be able to see both sides of the event:
+
+- `OrderService` publishes `OrderPlaced`.
+- `InventoryService` consumes `OrderPlaced`.
+
+Open the `Map` view from the event page to see the relationship visually.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-producer-consumer-map.png"
+    alt="The OrderPlaced event map showing OrderService as producer and InventoryService as consumer"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The OrderPlaced map showing OrderService publishing the event and InventoryService consuming it.</figcaption>
+</figure>
+
+:::tip Show the visualizer on the page
+You can embed the same kind of visualization directly into a documentation page with the [`NodeGraph`](/docs/development/components/components/nodegraph) component:
+
+```mdx
+<NodeGraph />
+```
+
+When used on a service or event page, `NodeGraph` renders the graph for the current resource.
+:::
+
+### What you have now
+
+Your catalog now knows:
+
+- `OrderPlaced` is an event.
+- `OrderPlaced` has a schema.
+- `OrderService` publishes `OrderPlaced`.
+- `InventoryService` consumes `OrderPlaced`.
+
+This is the first complete event relationship in the tutorial catalog.
+
+### Next
+
+Continue to [Add ownership](/docs/tutorial/add-ownership).