@eventcatalog/create-eventcatalog 4.3.2 → 4.3.4-beta.0

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx

@@ -0,0 +1,53 @@
+---
+id: warehouse-service
+version: 1.0.0
+name: Warehouse Service
+summary: |
+  Orchestrates picking and packing in the warehouse. It reacts to completed orders, creates picking jobs, and signals when an order is ready to ship.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-completed
+    version: 1.0.0
+sends:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+writesTo:
+  - id: warehouse-database
+readsFrom:
+  - id: warehouse-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/warehouse-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Warehouse Service** runs warehousing. When the Ordering domain publishes [[event|order-completed]], it creates a picking job in the [[container|warehouse-database]] for the [[service|picking-worker]] to work through. Once the order is packed it publishes [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Ready-for-shipping signal"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Completed orders to fulfil"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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

@@ -0,0 +1,44 @@
+---
+dictionary:
+  - id: Fulfilment
+    name: Fulfilment
+    summary: 'Everything that gets a confirmed order physically to the customer — stock, packing and shipping.'
+    icon: PackageCheck
+  - id: Stock
+    name: Stock
+    summary: 'The quantity of a product physically available to sell.'
+    description: |
+      Stock is owned by the Inventory System. Each product has an available quantity and a reserved
+      quantity. Stock is the source of truth for whether an order can be fulfilled.
+    icon: Boxes
+  - id: Reservation
+    name: Reservation
+    summary: 'A temporary hold on stock for a specific order, taken during checkout.'
+    description: |
+      A reservation guarantees stock is set aside for an order while payment is taken. It is held,
+      then either consumed when the order ships or released if checkout fails.
+    icon: BookmarkCheck
+  - id: Picking
+    name: Picking
+    summary: "Collecting an order's items from the warehouse shelves."
+    icon: Hand
+  - id: Packing
+    name: Packing
+    summary: 'Boxing up a picked order into one or more parcels ready for shipping.'
+    icon: Package
+  - id: Shipment
+    name: Shipment
+    summary: 'A packed order handed to a carrier for delivery, tracked from dispatch to delivery.'
+    description: |
+      A shipment is created with an external carrier once an order is packed. Its lifecycle —
+      created, delivered or failed — is reported back by the carrier.
+    icon: Truck
+  - id: Carrier
+    name: Carrier
+    summary: 'The external delivery company that transports shipments to customers.'
+    icon: Globe
+  - id: Tracking Number
+    name: Tracking Number
+    summary: "A code from the carrier that lets the customer follow a shipment's progress."
+    icon: ScanBarcode
+---

package/templates/default/domains/Ordering/entities/checkout-session/index.mdx

@@ -0,0 +1,36 @@
+---
+id: checkout-session
+name: Checkout Session
+version: 1.0.0
+identifier: checkoutSessionId
+aggregateRoot: true
+summary: The orchestration state for turning a checked-out cart into an order.
+owners:
+  - ordering-platform
+properties:
+  - name: checkoutSessionId
+    type: UUID
+    required: true
+    description: Unique checkout session identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart being checked out.
+    references: cart
+    relationType: startsFrom
+    referencesIdentifier: cartId
+  - name: status
+    type: string
+    required: true
+    description: Current checkout state.
+  - name: startedAt
+    type: datetime
+    required: true
+    description: Time checkout orchestration started.
+---
+
+## Overview
+
+Checkout Session tracks the saga managed by [[service|checkout-orchestrator]] across inventory reservation, payment authorization and order creation.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order/index.mdx

@@ -0,0 +1,36 @@
+---
+id: order
+name: Order
+version: 1.0.0
+identifier: orderId
+aggregateRoot: true
+summary: The durable customer order created after successful checkout.
+owners:
+  - ordering-platform
+properties:
+  - name: orderId
+    type: UUID
+    required: true
+    description: Unique order identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who placed the order.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current order lifecycle state.
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: Total order value at creation.
+---
+
+## Overview
+
+Order is the main aggregate in [[system|order-management-system]]. It emits order lifecycle events used by Fulfilment and support workflows.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order-line/index.mdx

@@ -0,0 +1,38 @@
+---
+id: order-line
+name: Order Line
+version: 1.0.0
+identifier: orderLineId
+summary: A purchased product and quantity within an order.
+owners:
+  - ordering-platform
+properties:
+  - name: orderLineId
+    type: UUID
+    required: true
+    description: Unique order line identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order this line belongs to.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product purchased.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity purchased.
+---
+
+## Overview
+
+Order Line snapshots the products bought at checkout. It should not replace the Catalog domain's authoritative product data.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order-status-history/index.mdx

@@ -0,0 +1,35 @@
+---
+id: order-status-history
+name: Order Status History
+version: 1.0.0
+identifier: orderStatusHistoryId
+summary: Audit history of order lifecycle state changes.
+owners:
+  - ordering-platform
+properties:
+  - name: orderStatusHistoryId
+    type: UUID
+    required: true
+    description: Unique status history record.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order whose status changed.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: status
+    type: string
+    required: true
+    description: New order status.
+  - name: changedAt
+    type: datetime
+    required: true
+    description: Time the status changed.
+---
+
+## Overview
+
+Order Status History provides an audit trail for customer support, fulfilment exceptions and order lifecycle debugging.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/flows/PlaceAnOrder/index.mdx

@@ -0,0 +1,158 @@
+---
+id: place-an-order
+name: Place an Order
+version: 1.0.0
+summary: |
+  The end-to-end journey from a customer checking out their cart to a confirmed order — spanning the Shopping and Ordering domains, including the checkout saga and its failure path.
+owners:
+  - ordering-platform
+steps:
+  - id: shopper_checks_out
+    title: Shopper checks out
+    actor:
+      name: Shopper
+      summary: The customer confirms their cart and starts checkout.
+    next_step:
+      id: checkout_cart_command
+      label: Check out cart
+
+  - id: checkout_cart_command
+    title: Checkout Cart
+    message:
+      id: checkout-cart
+      version: 1.0.0
+    next_step:
+      id: cart_api
+      label: Price and finalise cart
+
+  - id: cart_api
+    title: Cart API
+    service:
+      id: cart-api
+      version: 1.0.0
+    next_step:
+      id: cart_checked_out
+      label: Publish checkout
+
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Start checkout flow
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: checkout_orchestrator
+      label: Run checkout saga
+
+  - id: checkout_orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_steps:
+      - id: reserve_inventory
+        label: Reserve inventory
+      - id: authorize_payment
+        label: Authorize payment
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_step:
+      id: authorize_payment
+      label: Inventory held
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Payment authorized
+      - id: checkout_failed
+        label: Authorization declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Persist order
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_step:
+      id: order_created
+      label: Publish order created
+
+  - id: order_created
+    title: Order Created
+    message:
+      id: order-created
+      version: 1.0.0
+    next_step:
+      id: order_confirmed
+      label: Confirm to customer
+
+  - id: order_confirmed
+    title: Order confirmed
+    custom:
+      title: Order confirmed
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: The customer's order is placed and confirmed. Fulfilment begins.
+      properties:
+        happy_path: 'true'
+
+  - id: checkout_failed
+    title: Checkout failed
+    custom:
+      title: Checkout failed
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: A checkout step failed (e.g. payment declined). The orchestrator compensates earlier steps and cancels the order.
+      properties:
+        common_causes: 'payment declined, out of stock'
+        next_action: 'release reservation, void authorization, cancel order'
+    next_step:
+      id: order_cancelled
+      label: Cancel order
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+---
+
+## Overview
+
+**Place an Order** is the headline business flow at Acme Inc. It begins in the [[domain|shopping]] domain, when a shopper checks out their cart, and finishes in the [[domain|ordering]] domain, with a confirmed order — or a compensated, cancelled one if a step fails.
+
+<NodeGraph />
+
+## How it works
+
+1. The shopper checks out — the [[service|cart-api]] prices the cart and publishes [[event|cart-checked-out]].
+2. The [[service|checkout-api]] picks this up and hands it to the [[service|checkout-orchestrator]].
+3. The orchestrator runs the saga: [[command|reserve-inventory]] then [[command|authorize-payment]].
+4. On success it sends [[command|create-order]] to the [[service|order-service]], which publishes [[event|order-created]].
+5. If any step fails, the orchestrator compensates the earlier steps and the order is cancelled via [[event|order-cancelled]].

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

@@ -0,0 +1,70 @@
+---
+id: ordering
+name: Ordering
+version: 1.0.0
+summary: |
+  The Ordering domain turns a checked-out cart into a confirmed order. It orchestrates checkout — reserving inventory, authorizing payment and creating the order — and owns the lifecycle of every order.
+owners:
+  - ordering-platform
+systems:
+  - id: checkout-system
+    version: 1.0.0
+  - id: order-management-system
+    version: 1.0.0
+flows:
+  - id: place-an-order
+    version: 1.0.0
+entities:
+  - id: checkout-session
+    version: 1.0.0
+  - id: order
+    version: 1.0.0
+  - id: order-line
+    version: 1.0.0
+  - id: order-status-history
+    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 **Ordering** domain is responsible for everything that happens once a customer commits to buy — from the moment their cart is checked out to a confirmed, fulfilled order. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/checkout-system/1.0.0"
+    title="Checkout System"
+    description="Orchestrates checkout — reserves inventory, authorizes payment and creates the order."
+  />
+  <Tile
+    icon="ClipboardDocumentListIcon"
+    href="/docs/systems/order-management-system/1.0.0"
+    title="Order Management System"
+    description="System of record for orders and their lifecycle."
+  />
+</Tiles>
+
+### How the systems work together
+
+When the [[domain|shopping]] domain checks out a cart, the **Checkout System** takes over. It orchestrates the steps needed to place an order — reserving inventory, authorizing payment, and finally asking the **Order Management System** to create the order. The Order Management System then owns that order for the rest of its life, publishing events as it is created, completed or cancelled.
+
+## 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/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx

@@ -0,0 +1,101 @@
+---
+id: checkout-saga
+name: Checkout Saga
+version: 1.0.0
+summary: |
+  How the Checkout Orchestrator turns a checked-out cart into an order — reserving inventory, authorizing payment and creating the order, with compensation when a step fails.
+owners:
+  - ordering-platform
+steps:
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Receive checkout
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: orchestrator
+      label: Start saga
+
+  - id: orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_step:
+      id: reserve_inventory
+      label: Step 1 — reserve inventory
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_steps:
+      - id: authorize_payment
+        label: Reserved
+      - id: compensate_release
+        label: Out of stock
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Authorized
+      - id: compensate_release
+        label: Declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: saga_complete
+      label: Order created
+
+  - id: saga_complete
+    title: Saga complete
+    custom:
+      title: Saga complete
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: Inventory reserved, payment authorized and order created. The saga succeeds.
+
+  - id: compensate_release
+    title: Compensate
+    custom:
+      title: Compensate and abort
+      color: red
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: A step failed. The orchestrator releases any reservation and voids any authorization, then aborts the saga without creating an order.
+      properties:
+        actions: 'release reservation, void authorization'
+---
+
+## Overview
+
+The **Checkout Saga** is the heart of the [[system|checkout-system]]. It coordinates the steps that turn a checked-out cart into a confirmed order. Each step has a compensating action so a failure never leaves the customer in an inconsistent state.
+
+<NodeGraph />
+
+## Steps
+
+1. **Reserve inventory** — [[command|reserve-inventory]] holds stock for the cart's items.
+2. **Authorize payment** — [[command|authorize-payment]] places a hold on the order total.
+3. **Create order** — [[command|create-order]] persists the order in the [[system|order-management-system]].
+
+If reservation or authorization fails, the orchestrator **compensates** — releasing the reservation and voiding the authorization — and aborts without creating an order.

package/templates/default/domains/Ordering/systems/checkout-system/index.mdx

@@ -0,0 +1,57 @@
+---
+id: checkout-system
+name: Checkout System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates checkout. When a cart is checked out it reserves inventory, authorizes payment, and asks the Order Management System to create the order.
+owners:
+  - ordering-platform
+services:
+  - id: checkout-api
+  - id: checkout-orchestrator
+flows:
+  - id: checkout-saga
+    version: 1.0.0
+relationships:
+  - id: order-management-system
+    label: creates orders via
+actors:
+  - id: shopper
+    name: Shopper
+    label: confirms checkout
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Checkout System** drives the checkout flow at Acme Inc. When the [[domain|shopping]] domain checks out a cart, the [[service|checkout-api]] receives the [[command|checkout-cart]] command and hands it to the [[service|checkout-orchestrator]]. The orchestrator runs the checkout saga — reserving inventory via [[command|reserve-inventory]], authorizing payment via [[command|authorize-payment]], and finally creating the order via [[command|create-order]] against the [[system|order-management-system]].
+
+## 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\|checkout-api]]          | Service | Entry point for checkout. Receives the checkout command and starts the flow. |
+| [[service\|checkout-orchestrator]] | Service | Runs the checkout saga — reserve inventory, authorize payment, create order. |
+
+## Messages this system sends
+
+- [[command\|reserve-inventory]] — reserve stock for the items in the cart.
+- [[command\|authorize-payment]] — authorize payment for the order total.
+- [[command\|create-order]] — create the order in the Order Management System.

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx

@@ -0,0 +1,53 @@
+---
+id: checkout-api
+version: 1.0.0
+name: Checkout API
+summary: |
+  The entry point to the Checkout System. Receives the checkout command from the Shopping domain and starts the checkout flow.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+receives:
+  - id: checkout-cart
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout API** is the front door to the Checkout System. When the [[domain|shopping]] domain checks out a cart, this service receives the [[command|checkout-cart]] command, validates it, and hands the work to the [[service|checkout-orchestrator]] to run the checkout saga.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="The checkout command from Shopping"
+  />
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/services/checkout-orchestrator/1.0.0"
+    title="Delegates to the Orchestrator"
+    description="The saga that runs checkout"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area                  | Description                                                                 |
+| --------------------- | --------------------------------------------------------------------------- |
+| Checkout entry        | Receives and validates [[command\|checkout-cart]] from the Shopping domain. |
+| Orchestration handoff | Starts a checkout saga in the [[service\|checkout-orchestrator]].           |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />