@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/owners/automated-teams-and-users/sync-from-microsoft-entra.md

@@ -0,0 +1,253 @@
+---
+sidebar_position: 2
+slug: /development/guides/owners/sync-from-microsoft-entra
+keywords:
+- EventCatalog Microsoft Entra connector
+- sync Microsoft Entra teams users
+- sync Azure AD groups users
+- directory connector
+sidebar_label: Sync from Microsoft Entra ID
+title: Sync from Microsoft Entra ID
+description: Sync Microsoft Entra ID groups and direct members into EventCatalog as teams and users.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+<AddedIn version="3.45.0" pkg="@eventcatalog/connectors" />
+
+In EventCatalog, you can import and sync your users and teams directly from Microsoft Entra ID. Instead of adding people and teams by hand, you point EventCatalog at selected Entra groups and the catalog keeps those teams and their direct members in sync.
+
+```mermaid
+flowchart LR
+    E[Microsoft Entra ID] --> C[Microsoft Entra connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Why sync from Microsoft Entra ID
+
+Teams and users in EventCatalog are used to assign ownership to resources such as services, events, domains, and more. Many organizations already manage team membership in Microsoft Entra ID. Syncing from Entra keeps ownership data aligned with the directory your organization already maintains.
+
+## How it works
+
+When EventCatalog starts, the connector fetches the configured Entra groups from Microsoft Graph. Each selected group becomes an EventCatalog team, and each direct enabled user member becomes an EventCatalog user.
+
+Synced teams and users appear alongside locally authored users and teams. Each synced entry is marked as read-only and surfaced in directory source badges so people know the source of truth is Microsoft Entra ID.
+
+## Install
+
+```bash
+npm install @eventcatalog/connectors
+```
+
+## Configure
+
+Import `microsoftEntraDirectory` and add it to the `directory.sources` array in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { microsoftEntraDirectory } from '@eventcatalog/connectors';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [
+      microsoftEntraDirectory({
+        // Directory (tenant) ID from your Microsoft Entra app registration.
+        tenantId: process.env.AZURE_TENANT_ID,
+
+        // Application (client) ID from your Microsoft Entra app registration.
+        clientId: process.env.AZURE_CLIENT_ID,
+
+        // Client secret value from Certificates & secrets.
+        // Use the secret value, not the secret ID.
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+
+        // Entra groups to sync into EventCatalog as teams.
+        groups: [
+          {
+            // Stable Entra group Object ID. Recommended because it is unique and does not change if the group is renamed.
+            id: '00000000-0000-0000-0000-000000000000',
+
+            // Optional EventCatalog team id. If omitted, the connector slugifies the Entra group display name.
+            alias: 'platform',
+          },
+          {
+            // You can also sync by exact display name. If more than one group matches, use the group Object ID instead.
+            displayName: 'Architecture Guild',
+          },
+        ],
+      }),
+    ],
+  },
+};
+```
+
+## Microsoft Entra app registration
+
+The connector uses Microsoft Graph with the OAuth client credentials flow.
+
+1. In Azure Portal, open **Microsoft Entra ID**.
+2. Go to **App registrations** and create a new app registration.
+3. Copy the **Directory (tenant) ID** into `AZURE_TENANT_ID`.
+4. Copy the **Application (client) ID** into `AZURE_CLIENT_ID`.
+5. Go to **Certificates & secrets** and create a new client secret.
+6. Copy the secret **Value** into `AZURE_CLIENT_SECRET`. You do not need the secret ID.
+7. Go to **API permissions** and add these Microsoft Graph **Application permissions**:
+   - `Group.Read.All` - read the configured groups.
+   - `GroupMember.Read.All` - read direct members of the configured groups.
+   - `User.Read.All` - read user profile fields for synced members.
+8. Grant admin consent for the permissions.
+
+Pass the credentials with environment variables:
+
+```bash
+AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000 \
+AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000 \
+AZURE_CLIENT_SECRET=your-secret-value \
+npx eventcatalog dev
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `tenantId` | `string` | Yes | Microsoft Entra tenant ID. |
+| `clientId` | `string` | Yes | Application/client ID for the app registration. |
+| `clientSecret` | `string` | Yes | Client secret value for the app registration. |
+| `groups` | `(string \| { id: string; alias?: string } \| { displayName: string; alias?: string })[]` | Yes | Entra groups to sync. Group IDs are recommended. |
+| `users` | `boolean` | No | When `true` (default), direct members of every synced group are also synced as users. Set to `false` to sync teams only. |
+| `includeDisabledUsers` | `boolean` | No | Disabled users are excluded by default. Set to `true` to include them. |
+| `graphBaseUrl` | `string` | No | Override the Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`. Useful for sovereign cloud environments. |
+| `tokenUrl` | `string` | No | Override the OAuth token URL. Defaults to `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`. Useful for sovereign cloud environments. |
+
+## Selecting groups
+
+Groups can be configured by stable group ID:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [
+    {
+      // Stable Entra group Object ID. Recommended because it is unique and does not change if the group is renamed.
+      id: 'e3d11d65-178c-45ff-a9e0-a1d4b74006ff',
+
+      // Optional EventCatalog team id. Use this in owner frontmatter, for example `owners: ['platform-engineering']`.
+      alias: 'platform-engineering',
+    },
+  ],
+});
+```
+
+You can also configure a group by exact display name:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [
+    {
+      // Exact Entra group display name. If more than one group has this name, use the group Object ID instead.
+      displayName: 'Platform Engineering',
+
+      // Optional EventCatalog team id. If omitted, the connector slugifies the display name.
+      alias: 'platform-engineering',
+    },
+  ],
+});
+```
+
+Group IDs are recommended because they are stable and unique. If a `displayName` lookup finds no groups or more than one group, EventCatalog stops the build and asks you to use the group ID instead.
+
+## What gets synced
+
+### Teams
+
+Each configured Entra group creates a team entry with:
+
+- `id` set to `alias` when provided, otherwise a slugified version of the Entra group display name.
+- `name` taken from the Entra group display name.
+- `summary` taken from the Entra group description.
+- `email` taken from the Entra group mail address when available.
+- `source.provider` set to `microsoft-entra`.
+- `source.id` set to the Entra group object ID.
+- A read-only note explaining the team is managed in Microsoft Entra ID.
+
+### Users
+
+Users are synced only from the configured groups. When `users` is `true`, every direct enabled user member of each synced group is fetched and created as a user entry with:
+
+- `id` set to the user's mail address when available.
+- Guest user principal names such as `name_example.com#EXT#@tenant.onmicrosoft.com` normalized back to `name@example.com` when no mail address is available.
+- `id` set to the user's user principal name when no mail address is available and the user is not a guest account.
+- `id` set to the Microsoft Graph user object ID when no mail address or user principal name is available.
+- `name` taken from the Entra user display name.
+- `email` taken from the user's mail address or user principal name.
+- `role` taken from the user's job title.
+- `source.provider` set to `microsoft-entra`.
+- `source.id` set to the Entra user object ID.
+- A read-only note explaining the user is managed in Microsoft Entra ID.
+
+Profile photos are not fetched. User avatars are optional in EventCatalog.
+
+:::info Direct members only
+
+The connector syncs direct user members of the configured groups. It does not expand nested groups or transitive membership in this version.
+
+:::
+
+## Use synced owners
+
+Synced teams and users behave identically to hand-authored ones. Reference them by their `id` in any resource frontmatter:
+
+```yaml title="services/order-service/index.md"
+---
+id: OrderService
+name: Order Service
+owners:
+  - platform-engineering
+  - dave@eventcatalog.dev
+---
+```
+
+## Conflict strategy
+
+When a locally authored user or team shares the same `id` as one returned by the connector, EventCatalog uses the `conflictStrategy` setting to decide what to do.
+
+| Strategy | Behaviour |
+|---|---|
+| `local-wins` (default) | The local file is kept and the external entry is skipped. |
+| `source-wins` | The external entry overwrites the local file. |
+| `error` | EventCatalog throws an error and stops the build. |
+
+Configure the strategy in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... rest of config
+  directory: {
+    conflictStrategy: 'local-wins',
+    sources: [ /* ... */ ],
+  },
+};
+```
+
+## Sovereign cloud endpoints
+
+For sovereign cloud environments, override the Graph and token endpoints:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [{ id: '00000000-0000-0000-0000-000000000000' }],
+  graphBaseUrl: 'https://graph.microsoft.com/v1.0',
+  tokenUrl: 'https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token',
+});
+```

package/dist/docs/development/guides/resources/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Resources",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources",
+    "description": "Guides for documenting EventCatalog resources such as services, messages, schemas, data stores, data products, entities, agents, flows, and architecture decision records."
+  }
+}

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

@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog ADR
+- architecture decision records
+- ADR documentation
+sidebar_label: What are ADRs?
+title: What are architecture decision records?
+description: Document and govern architectural choices alongside your catalog resources.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice. In EventCatalog, ADRs are first-class resources that live alongside services, events, domains, and flows.
+
+Architectural choices are often made once and then forgotten. When a new engineer joins or a design is revisited months later, the reasoning behind past decisions is usually lost.
+
+Documenting ADRs in your catalog gives your team:
+
+- **Context** — anyone can see what alternatives were considered and why a particular path was chosen.
+- **Traceability** — decisions are linked directly to the services, events, domains, and flows they affect via `appliesTo`.
+- **Lifecycle tracking** — each ADR has a status (`proposed`, `accepted`, `rejected`, `deprecated`, `superseded`) so it is clear which decisions are still in force.
+- **AI-ready context** — because ADRs sit alongside the resources they govern, the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) can surface the *why* behind your architecture to AI assistants, not just the *what*. When an LLM is reasoning about a service or event, it picks up the decisions, trade-offs, and constraints recorded in your ADRs.
+
+## Lifecycle statuses
+
+Every ADR must declare a `status` field. The available values are:
+
+| Status | Meaning |
+| --- | --- |
+| `proposed` | Under discussion, not yet accepted |
+| `accepted` | In force |
+| `rejected` | Considered and deliberately not adopted |
+| `deprecated` | Was accepted but is being phased out |
+| `superseded` | Replaced by a newer decision |
+
+EventCatalog renders a colored badge for each status and shows a warning banner on `deprecated` and `superseded` pages so readers are directed to the current decision.

package/dist/docs/development/guides/resources/adrs/02-creating-adrs.md

@@ -0,0 +1,211 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog ADR
+- create architecture decision records
+sidebar_label: Create an ADR
+title: Create an ADR
+description: Add architecture decision records to your catalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice and can be rendered and assigned to resources in EventCatalog.
+
+![Architecture decision record page in EventCatalog](./img/adr-overview.png)
+
+## Creating an ADR
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog ADR">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/adrs/creating-adrs.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/adrs.md then help me create a new EventCatalog architecture decision record in my catalog.
+
+Ask me for the decision title, context, decision, consequences, status, date, version, whether it belongs at the root of the catalog or inside a domain or system, and any resources it applies to. Then create the correct adrs/{'{ADR Name}'}/index.mdx, domains/{'{Domain Name}'}/adrs/{'{ADR Name}'}/index.mdx, or systems/{'{System Name}'}/adrs/{'{ADR Name}'}/index.mdx file with frontmatter and starter markdown.
+
+If I do not know the status, use proposed. If I do not provide a date, use today's date. If the ADR affects existing resources, add them to appliesTo.
+
+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 ADR should live, create the right folder structure, and write the first draft of the decision record.
+
+### Manual Creation
+
+ADRs live in an `adrs` folder. EventCatalog discovers any `index.mdx` file inside an `adrs` directory, regardless of where that directory lives in your catalog.
+
+You can place ADRs:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'adrs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'choose-kafka',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'adrs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'event-driven-orders',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+ADRs can also live inside a system folder when the decision is specific to that system.
+
+## Create the ADR file
+
+Create an `index.mdx` file for the ADR.
+
+Here is a minimal ADR with all required fields.
+
+```md title="adrs/choose-kafka/index.mdx"
+---
+# Unique identifier for the ADR. Used for URLs and references.
+id: choose-kafka
+
+# Display name rendered in EventCatalog.
+name: Choose Kafka for domain event distribution
+
+# Version of the ADR.
+version: 1.0.0
+
+# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
+status: accepted
+
+# Date the decision was made or proposed.
+date: 2026-05-26
+---
+
+## Context
+
+Services need a reliable backbone for cross-domain event distribution.
+
+## Decision
+
+We will use Apache Kafka as the primary event bus for inter-domain communication.
+
+## Consequences
+
+Teams gain reliable, ordered delivery with replay support. They also take on operational responsibility for the Kafka cluster.
+```
+
+## Add optional fields
+
+Enrich the ADR with owners, decision makers, links to affected resources, and badges.
+
+```md title="adrs/choose-kafka/index.mdx"
+---
+# Unique identifier for the ADR. Used for URLs and references.
+id: choose-kafka
+
+# Display name rendered in EventCatalog.
+name: Choose Kafka for domain event distribution
+
+# Short summary shown in lists and page headers.
+summary: Kafka is the primary backbone for inter-domain event distribution.
+
+# Version of the ADR.
+version: 1.0.0
+
+# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
+status: accepted
+
+# Date the decision was made or proposed.
+date: 2026-05-26
+
+# Optional owners. References team or user ids.
+owners:
+  - platform-team
+
+# Optional decision makers. References team or user ids.
+decisionMakers:
+  - architecture-board
+
+# Optional resources affected by this decision.
+appliesTo:
+  - type: domain
+    id: Orders
+  - type: service
+    id: PaymentService
+  - type: event
+    id: PaymentAccepted
+
+# Optional badges rendered on the ADR page.
+badges:
+  - content: Messaging
+    backgroundColor: blue
+    textColor: blue
+---
+
+## Context
+
+...
+
+## Decision
+
+...
+
+## Consequences
+
+...
+```
+
+## Recommended body structure
+
+EventCatalog does not enforce a particular body format, but the classic ADR structure works well.
+
+**Context** — the situation or problem that prompted the decision.
+
+**Decision** — the choice that was made and the reasoning behind it.
+
+**Consequences** — what happens as a result, both positive and negative.
+
+You can use any markdown content here including headings, tables, code blocks, and MDX components.
+
+## Next steps
+
+- [Link decisions to resources](/docs/development/guides/resources/adrs/linking-resources)
+- [Model relationships between decisions](/docs/development/guides/resources/adrs/relationships)
+- [Architecture decision records reference](/docs/development/guides/resources/adrs/reference)

package/dist/docs/development/guides/resources/adrs/03-linking-resources.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog ADR
+- link ADR to resources
+sidebar_label: Add ADRs to resources
+title: Add ADRs to resources
+description: Connect decisions to the services, events, and domains they affect.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Use `appliesTo` to connect an ADR to the catalog resources it affects. When resources are linked, the ADR appears in the **Decision Records** section of each resource's sidebar.
+
+![Decision Records section on a resource sidebar listing linked ADRs](./img/linked-adr-document.png)
+
+## Use `appliesTo`
+
+Add an `appliesTo` array to the frontmatter, specifying the `type` and `id` of each affected resource.
+
+```yaml title="adrs/choose-kafka/index.mdx"
+appliesTo:
+  #  ADR will apply to the Orders Domain
+  - type: domain
+    id: Orders
+  # ADR will apply to the PaymentService
+  - type: service
+    id: PaymentService
+  # ADR will apply to the PaymentAccepted event
+  - type: event
+    id: PaymentAccepted
+```
+
+## Pin to a specific version
+
+By default, EventCatalog resolves the link to the latest version of the resource. Add a `version` field to pin to a specific version.
+
+```yaml
+appliesTo:
+  - type: service
+    id: PaymentService
+    version: 1.0.0
+  - type: event
+    id: OrderConfirmed
+    version: latest   # explicit, same as omitting version
+```
+
+## How it appears in the UI
+
+When a resource has one or more ADRs linked via `appliesTo`, a **Decision Records** group appears in that resource's sidebar. Each linked ADR shows its name and links directly to the decision page.
+
+This means engineers reading a service or event page can immediately see which architectural choices affect it, without leaving the page.

package/dist/docs/development/guides/resources/adrs/04-relationships.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog ADR
+- supersedes
+- amends
+sidebar_label: Model ADR relationships
+title: Model ADR relationships
+description: Model how decisions supersede, amend, or relate to each other.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.42.0" />
+
+ADRs often build on or replace earlier decisions. EventCatalog supports four relationship types to capture this history.
+
+## Supersedes and supersededBy
+
+Use `supersedes` when a new decision replaces an older one. The older decision should set its `status` to `superseded`.
+
+```yaml title="adrs/adr-003-v2/index.mdx (new decision)"
+---
+id: adr-003-standardize-domain-event-buses
+version: 2.0.0
+status: accepted
+supersedes:
+  - id: adr-003-standardize-domain-event-buses
+    version: 1.0.0
+---
+```
+
+You can also declare the relationship from the older side using `supersededBy`.
+
+```yaml title="adrs/adr-003-v1/index.mdx (old decision)"
+---
+id: adr-003-standardize-domain-event-buses
+version: 1.0.0
+status: superseded
+supersededBy:
+  - id: adr-003-standardize-domain-event-buses
+    version: 2.0.0
+---
+```
+
+EventCatalog derives reverse links automatically. Declaring `supersedes` on the new decision is enough to infer the `supersededBy` relationship on the old one, and vice versa.
+
+## Amends and amendedBy
+
+Use `amends` when a decision refines or extends an earlier one without fully replacing it.
+
+```yaml
+amends:
+  - id: adr-001-choose-event-driven-orders
+```
+
+As with supersedes, reverse links are derived automatically from either side.
+
+## Related
+
+Use `related` to point to decisions that are relevant context but not in a supersedes or amends relationship.
+
+```yaml
+related:
+  - id: adr-001-choose-event-driven-orders
+  - id: adr-003-standardize-domain-event-buses
+    version: 2.0.0
+```
+
+## How relationships appear in the sidebar
+
+Each relationship group appears as a separate section in the ADR's sidebar:
+
+- **Supersedes** — decisions this ADR replaces
+- **Superseded by** — decisions that replace this ADR
+- **Amends** — decisions this ADR refines
+- **Amended by** — decisions that refine this ADR
+- **Related decisions** — associated decisions
+
+Deprecated and superseded ADRs also display a warning banner at the top of the page with links to the current decision.