@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

package/templates/default/domains/Customer/systems/identity-provider/index.mdx

@@ -0,0 +1,54 @@
+---
+id: identity-provider
+name: Identity Provider
+version: 1.0.0
+summary: |
+  The identity system that authenticates customers. It is the source of truth for credentials and login, verifies sign-in attempts, and emits an event when a customer successfully authenticates.
+scope: external
+owners:
+  - customer-platform
+services:
+  - id: oauth-api
+containers:
+  - id: user-directory
+relationships:
+  - id: customer-management-system
+    label: provides authentication for
+actors:
+  - id: customer
+    name: Customer
+    label: signs in
+    direction: inbound
+badges:
+  - content: Identity
+    backgroundColor: purple
+    textColor: purple
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Identity Provider** authenticates customers for Acme Inc. It exposes an OAuth-style API, verifies credentials against the [[container|user-directory]], and emits a [[event|customer-authenticated]] event on a successful sign-in so other systems can react. It provides authentication for the [[system|customer-management-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                     | Type       | Responsibility                                                                                       |
+| ----------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| [[service\|oauth-api]]        | Service    | OAuth-style authentication API. Handles authentication requests and publishes authentication events. |
+| [[container\|user-directory]] | Data store | The directory of customer credentials and identities.                                                |
+
+## Messages this system publishes
+
+- [[event|customer-authenticated]] — a customer has successfully authenticated.

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx

@@ -0,0 +1,32 @@
+---
+id: authenticate-customer
+name: Authenticate Customer
+version: 1.0.0
+summary: |
+  Command to authenticate a customer with their credentials.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /oauth/token
+  statusCodes: ['200', '400', '401']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthenticateCustomer` is handled by the [[service|oauth-api]]. It verifies the supplied credentials against the [[container|user-directory]] and, on success, returns an access token and publishes a [[event|customer-authenticated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthenticateCustomer",
+  "description": "Command to authenticate a customer with their credentials, and the token returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "The credentials to authenticate",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "password": {
+          "type": "string"
+        }
+      },
+      "required": ["email", "password"]
+    },
+    "response": {
+      "description": "The access token issued on a successful sign-in",
+      "type": "object",
+      "properties": {
+        "accessToken": {
+          "type": "string"
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["Bearer"]
+        },
+        "expiresIn": {
+          "description": "Token lifetime in seconds",
+          "type": "integer"
+        }
+      },
+      "required": ["accessToken", "tokenType", "expiresIn"]
+    }
+  },
+  "required": ["request", "response"]
+}

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: customer-authenticated
+name: Customer Authenticated
+version: 1.0.0
+summary: |
+  Published when a customer has successfully authenticated.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerAuthenticated` is published by the [[service|oauth-api]] whenever a customer successfully signs in. Other systems consume this event for auditing, session tracking, and security monitoring.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerAuthenticated",
+  "description": "Emitted when a customer successfully authenticates",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer authenticated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier of the customer that authenticated",
+      "type": "string",
+      "format": "uuid"
+    },
+    "method": {
+      "description": "How the customer authenticated",
+      "type": "string",
+      "enum": ["PASSWORD", "SSO", "MFA"]
+    },
+    "ipAddress": {
+      "description": "IP address the sign-in came from",
+      "type": "string"
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "method"]
+}

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx

@@ -0,0 +1,59 @@
+---
+id: oauth-api
+version: 1.0.0
+name: OAuth API
+summary: |
+  OAuth-style authentication API for the Identity Provider. Verifies customer credentials and publishes an event when a customer successfully authenticates.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: authenticate-customer
+    version: 1.0.0
+sends:
+  - id: customer-authenticated
+    version: 1.0.0
+readsFrom:
+  - id: user-directory
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/oauth-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **OAuth API** is the authentication entry point for Acme Inc. It verifies credentials against the [[container|user-directory]] and, on a successful sign-in, publishes a [[event|customer-authenticated]] event so other systems can react.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Authentication events published on successful sign-in"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Authentication requests handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| Authentication   | Handles [[command\|authenticate-customer]] and verifies credentials.                |
+| Event publishing | Emits [[event\|customer-authenticated]] on a successful sign-in.                    |
+| Credentials      | Reads from the [[container\|user-directory]] — the source of truth for credentials. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />

package/templates/default/domains/Customer/ubiquitous-language.mdx

@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Customer
+    name: Customer
+    summary: 'A person with an account at Acme Inc, identified by a unique customer id and email.'
+    description: |
+      The customer is the central concept of the Customer domain. Their profile is owned by the
+      Customer Management System, which is the source of truth for who a customer is. A customer has:
+
+      - A unique customer id and a unique email
+      - A display name
+      - An account status (ACTIVE, SUSPENDED or CLOSED)
+
+      A customer's profile data is kept deliberately separate from their credentials, which live in
+      the Identity Provider.
+    icon: User
+  - id: Identity
+    name: Identity
+    summary: 'The credentials and login information used to prove a customer is who they say they are.'
+    description: |
+      An identity is distinct from a customer profile. It lives in the Identity Provider's user
+      directory and holds the login email and a securely hashed credential. Keeping identity separate
+      from profile data isolates the most sensitive information.
+    icon: Fingerprint
+  - id: Authentication
+    name: Authentication
+    summary: 'Verifying that a sign-in attempt belongs to a real customer.'
+    description: |
+      Authentication is owned by the Identity Provider. It verifies credentials against the user
+      directory and, on success, issues an access token and publishes a CustomerAuthenticated event.
+    icon: LockKeyhole
+  - id: Credential
+    name: Credential
+    summary: 'A secret (such as a password) a customer uses to authenticate. Never stored in plain text.'
+    icon: KeyRound
+  - id: Account Status
+    name: Account Status
+    summary: 'Where a customer account sits: ACTIVE, SUSPENDED or CLOSED.'
+    description: |
+      - ACTIVE — the account is in good standing and can be used.
+      - SUSPENDED — temporarily blocked (e.g. for review).
+      - CLOSED — permanently deactivated.
+    icon: Workflow
+  - id: User Directory
+    name: User Directory
+    summary: 'The authoritative store of customer credentials and login identities.'
+    icon: Users
+---

package/templates/default/domains/Fulfilment/entities/inventory-reservation/index.mdx

@@ -0,0 +1,39 @@
+---
+id: inventory-reservation
+name: Inventory Reservation
+version: 1.0.0
+identifier: reservationId
+aggregateRoot: true
+summary: Stock held for a checkout or order before fulfilment.
+owners:
+  - fulfilment-platform
+properties:
+  - name: reservationId
+    type: UUID
+    required: true
+    description: Unique reservation identifier.
+  - name: orderId
+    type: UUID
+    required: false
+    description: Order associated with the reservation once created.
+    references: order
+    relationType: reservedFor
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being reserved.
+    references: product
+    relationType: reserves
+    referencesIdentifier: productId
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the reservation expires if not committed.
+---
+
+## Overview
+
+Inventory Reservation is created during checkout by [[command|reserve-inventory]] and released if the saga fails.
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/entities/shipment/index.mdx

@@ -0,0 +1,36 @@
+---
+id: shipment
+name: Shipment
+version: 1.0.0
+identifier: shipmentId
+aggregateRoot: true
+summary: A carrier delivery for a packed customer order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: shipmentId
+    type: UUID
+    required: true
+    description: Unique shipment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being shipped.
+    references: order
+    relationType: ships
+    referencesIdentifier: orderId
+  - name: carrierReference
+    type: string
+    required: false
+    description: External carrier tracking reference.
+  - name: status
+    type: string
+    required: true
+    description: Shipment delivery status.
+---
+
+## Overview
+
+Shipment is created by the Shipping System and updated from carrier events such as [[event|shipment-created]] and [[event|shipment-delivered]].
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/entities/stock-item/index.mdx

@@ -0,0 +1,36 @@
+---
+id: stock-item
+name: Stock Item
+version: 1.0.0
+identifier: stockItemId
+aggregateRoot: true
+summary: The inventory record for a product variant at a location.
+owners:
+  - fulfilment-platform
+properties:
+  - name: stockItemId
+    type: UUID
+    required: true
+    description: Unique stock item identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product held in stock.
+    references: product
+    relationType: stocks
+    referencesIdentifier: productId
+  - name: locationId
+    type: string
+    required: true
+    description: Warehouse or fulfilment location.
+  - name: availableQuantity
+    type: integer
+    required: true
+    description: Quantity available to reserve.
+---
+
+## Overview
+
+Stock Item is the Inventory System's view of available stock for a product at a fulfilment location.
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/entities/warehouse-pick/index.mdx

@@ -0,0 +1,35 @@
+---
+id: warehouse-pick
+name: Warehouse Pick
+version: 1.0.0
+identifier: pickId
+summary: A warehouse task to pick items for a completed order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: pickId
+    type: UUID
+    required: true
+    description: Unique warehouse pick identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being picked.
+    references: order
+    relationType: fulfils
+    referencesIdentifier: orderId
+  - name: assignedTo
+    type: string
+    required: false
+    description: Warehouse worker or automation lane assigned.
+  - name: status
+    type: string
+    required: true
+    description: Pick task status.
+---
+
+## Overview
+
+Warehouse Pick represents the operational task handled by the Warehouse System before an order can be packed and shipped.
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/index.mdx

@@ -0,0 +1,83 @@
+---
+id: fulfilment
+name: Fulfilment
+version: 1.0.0
+summary: |
+  The Fulfilment domain gets a confirmed order to the customer. It reserves stock, picks and packs orders in the warehouse, and hands them to carriers for delivery.
+owners:
+  - fulfilment-platform
+systems:
+  - id: inventory-system
+    version: 1.0.0
+  - id: warehouse-system
+    version: 1.0.0
+  - id: shipping-system
+    version: 1.0.0
+  - id: carrier
+    version: 1.0.0
+entities:
+  - id: stock-item
+    version: 1.0.0
+  - id: inventory-reservation
+    version: 1.0.0
+  - id: warehouse-pick
+    version: 1.0.0
+  - id: shipment
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Fulfilment** domain is responsible for the physical side of an order — making sure stock is available, picking and packing it, and shipping it to the customer. It owns three internal systems and integrates with external carriers:
+
+<Tiles>
+  <Tile
+    icon="ArchiveBoxIcon"
+    href="/docs/systems/inventory-system/1.0.0"
+    title="Inventory System"
+    description="Tracks and reserves stock for orders."
+  />
+  <Tile
+    icon="BuildingStorefrontIcon"
+    href="/docs/systems/warehouse-system/1.0.0"
+    title="Warehouse System"
+    description="Picks and packs orders ready for shipping."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/systems/shipping-system/1.0.0"
+    title="Shipping System"
+    description="Hands packed orders to carriers for delivery."
+  />
+  <Tile
+    icon="GlobeAltIcon"
+    href="/docs/systems/carrier/1.0.0"
+    title="Carrier"
+    description="External carrier that delivers shipments to customers."
+  />
+</Tiles>
+
+### How the systems work together
+
+When an order is completed, the **Warehouse System** picks and packs it, having relied on the **Inventory System** to reserve stock earlier in checkout. Once packed, the **Shipping System** creates a shipment with an external **Carrier**, which delivers it to the customer and reports progress back.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />

package/templates/default/domains/Fulfilment/systems/carrier/index.mdx

@@ -0,0 +1,52 @@
+---
+id: carrier
+name: Carrier
+version: 1.0.0
+scope: external
+summary: |
+  External carrier that delivers shipments to customers. It accepts shipment requests and reports delivery progress back.
+owners:
+  - fulfilment-platform
+services:
+  - id: carrier-shipping-api
+  - id: carrier-tracking-api
+relationships:
+  - id: shipping-system
+    label: delivers shipments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+The **Carrier** is the external delivery company Acme Inc uses to ship orders to customers. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|shipping-system]] integrates with it.
+
+It receives [[command|create-shipment]] and reports progress back via [[event|shipment-created]], [[event|shipment-delivered]] and [[event|shipment-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type    | Responsibility                                    |
+| --------------------------------- | ------- | ------------------------------------------------- |
+| [[service\|carrier-shipping-api]] | Service | Accepts shipment requests and dispatches parcels. |
+| [[service\|carrier-tracking-api]] | Service | Reports delivery progress back to Acme Inc.       |
+
+## Messages this system publishes
+
+- [[event\|shipment-created]] — a shipment has been created and dispatched.
+- [[event\|shipment-delivered]] — a shipment was delivered to the customer.
+- [[event\|shipment-failed]] — a shipment could not be delivered.

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx

@@ -0,0 +1,40 @@
+---
+id: carrier-shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  The carrier's API for creating shipments. Acme Inc's Shipping System calls it to dispatch packed orders.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the carrier's external interface for creating shipments. The [[system|shipping-system]] sends [[command|create-shipment]], and the carrier dispatches the parcel and begins reporting progress through its [[service|carrier-tracking-api]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Shipment creation requests"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: shipment-created
+name: Shipment Created
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been created and dispatched.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentCreated` is published by the carrier's [[service|carrier-tracking-api]] when a shipment has been created and dispatched. Acme Inc consumes it to give the customer a tracking number and expected delivery date.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentCreated",
+  "description": "Published when a shipment has been created and dispatched",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "trackingNumber": { "type": "string" },
+    "carrier": { "type": "string" },
+    "estimatedDelivery": { "type": "string", "format": "date" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "trackingNumber", "createdAt"]
+}