Systems reference

View as Markdown

---

Added in eventcatalog@4.0

This page lists the fields, paths, and routes supported by systems.

Paths

Systems can be created at the root of your catalog:

/systems/{System Name}/index.mdx

Systems can also be created inside domains:

/domains/{Domain Name}/systems/{System Name}/index.mdx

Versioned systems use the same versioning pattern as other EventCatalog resources:

/systems/{System Name}/versioned/{version}/index.mdx
/domains/{Domain Name}/systems/{System Name}/versioned/{version}/index.mdx

Routes

Route	Description
/docs/systems/{system-id}/{version}	System documentation page.
/visualiser/systems/{system-id}/{version}	Resource diagram for one system.
/visualiser/systems/{system-id}/{version}/context	Context diagram for one system.
/visualiser/system-context-map	Global system context map.

Required fields

id

• Type: string

Unique id of the system. EventCatalog uses this for URLs and resource references.

Example

---
id: checkout-system
---

name

• Type: string

Display name of the system.

Example

---
name: Checkout System
---

version

• Type: string

Version of the system documentation.

Example

---
version: 1.0.0
---

Optional fields

summary

• Type: string

Short summary of what the system does.

Example

---
summary: Handles checkout, payment authorization, and order submission.
---

owners

• Type: array

An array of team or user ids that own the system.

Example

---
owners:
  - checkout-platform
---

scope

• Type: internal or external

Whether the system is owned by your organization or is an external system. Defaults to internal.

Example

---
scope: external
---

services

• Type: array

Services that belong to the system.

Example

---
services:
  - id: checkout-api
    version: 1.0.0
---

flows

• Type: array

Flows that belong to the system.

Example

---
flows:
  - id: checkout-flow
    version: 1.0.0
---

entities

• Type: array

Entities that belong to the system.

Example

---
entities:
  - id: order
    version: 1.0.0
---

containers

• Type: array

Containers or data stores that belong to the system.

Example

---
containers:
  - id: checkout-database
    version: 1.0.0
---

relationships

• Type: array

Other systems this system relates to.

Example

---
relationships:
  - id: promotion-system
    version: 1.0.0
    label: calculates discounts via
---

actors

• Type: array

People, roles, or external actors that interact with the system.

Example

---
actors:
  - id: shopper
    name: Shopper
    label: adds items and checks out
    direction: inbound
---

badges

• Type: array

Badges rendered on the system page.

Example

---
badges:
  - content: Critical
    backgroundColor: red
    textColor: red
---

repository

• Type: object

Repository metadata for the system.

Example

---
repository:
  language: TypeScript
  url: https://github.com/acme/checkout
---

diagrams

• Type: array

Diagrams associated with the system.

Example

---
diagrams:
  - id: checkout-deployment
    version: 1.0.0
---

attachments

• Type: array

External links or supporting documents attached to the system.

Example

---
attachments:
  - title: Checkout runbook
    url: https://runbooks.example.com/checkout
    type: runbook
---

Resource pointers

Systems reference resources using id and optional version.

---
services:
  - id: cart-api
    version: 1.0.0
containers:
  - id: cart-database
flows:
  - id: checkout-flow
entities:
  - id: cart
---

If version is omitted, EventCatalog uses the latest version.

Relationship fields

Relationships connect one system to another system.

---
relationships:
  - id: promotion-system
    version: 1.0.0
    label: calculates discounts via
---

Field	Type	Description
id	string	Target system id.
version	string	Target system version. Optional. Defaults to latest.
label	string	Text shown on the relationship edge.

Relationships are one-directional. Define the relationship on the system that owns the source of the relationship.

Actor fields

Actors are people, roles, or external participants that interact with a system.

---
actors:
  - id: shopper
    name: Shopper
    label: adds items and checks out
    direction: inbound
---

Field	Type	Description
id	string	Unique actor id.
name	string	Display name shown in diagrams. Optional.
label	string	Text shown on the actor relationship edge. Optional.
direction	inbound or outbound	inbound means actor to system. outbound means system to actor. Defaults to inbound.