# Systems reference

Copy as Markdown[View as Markdown](/docs/development/guides/systems/reference.md)

***

**Added in** `eventcatalog@4.0`

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

## Paths[​](#paths "Direct link to 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[​](#routes "Direct link to 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[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `string`

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

Example

```
---
id: checkout-system
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

Display name of the system.

Example

```
---
name: Checkout System
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the system documentation.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short summary of what the system does.

Example

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

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

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

Example

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

### `scope`[​](#scope "Direct link to 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`[​](#services "Direct link to services")

* Type: `array`

Services that belong to the system.

Example

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

### `flows`[​](#flows "Direct link to flows")

* Type: `array`

Flows that belong to the system.

Example

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

### `entities`[​](#entities "Direct link to entities")

* Type: `array`

Entities that belong to the system.

Example

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

### `containers`[​](#containers "Direct link to containers")

* Type: `array`

Containers or data stores that belong to the system.

Example

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

### `relationships`[​](#relationships "Direct link to relationships")

* Type: `array`

Other systems this system relates to.

Example

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

### `actors`[​](#actors "Direct link to 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`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the system page.

Example

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

### `repository`[​](#repository "Direct link to repository")

* Type: `object`

Repository metadata for the system.

Example

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

### `diagrams`[​](#diagrams "Direct link to diagrams")

* Type: `array`

Diagrams associated with the system.

Example

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

### `attachments`[​](#attachments "Direct link to 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[​](#resource-pointers "Direct link to 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[​](#relationship-fields "Direct link to 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[​](#actor-fields "Direct link to 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`. |