@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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 />

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx

@@ -0,0 +1,32 @@
+---
+id: authorize-payment
+name: Authorize Payment
+version: 1.0.0
+summary: |
+  Command to authorize payment for the total of a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /payments/authorize
+  statusCodes: ['201', '400', '402', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthorizePayment` is sent by the [[service|checkout-orchestrator]] to authorize payment for the order total. Authorization places a hold on the customer's payment method; the funds are captured once the order is created. If a later step fails, the authorization is voided.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthorizePayment",
+  "description": "Command to authorize payment for the total of a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer paying",
+      "type": "string",
+      "format": "uuid"
+    },
+    "amount": {
+      "description": "Amount to authorize, in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["cartId", "amount", "currency"]
+}

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx

@@ -0,0 +1,32 @@
+---
+id: reserve-inventory
+name: Reserve Inventory
+version: 1.0.0
+summary: |
+  Command to reserve stock for the items in a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReserveInventory` is sent by the [[service|checkout-orchestrator]] to hold stock for the items in a checked-out cart. A successful reservation guarantees the inventory is available while payment is authorized. If a later checkout step fails, the reservation is released.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReserveInventory",
+  "description": "Command to reserve stock for the items in a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items to reserve",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "required": ["productId", "quantity"]
+      }
+    }
+  },
+  "required": ["cartId", "items"]
+}

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

@@ -0,0 +1,59 @@
+---
+id: checkout-orchestrator
+version: 1.0.0
+name: Checkout Orchestrator
+summary: |
+  Runs the checkout saga. Reserves inventory, authorizes payment and creates the order, coordinating the steps that turn a checked-out cart into a confirmed order.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+sends:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: authorize-payment
+    version: 1.0.0
+  - id: create-order
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-orchestrator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout Orchestrator** is the brain of the Checkout System. Once the [[service|checkout-api]] hands it a checkout, it runs the checkout saga step by step:
+
+1. **Reserve inventory** — sends [[command|reserve-inventory]] to hold stock for the cart's items.
+2. **Authorize payment** — sends [[command|authorize-payment]] to authorize the order total.
+3. **Create the order** — sends [[command|create-order]] to the [[system|order-management-system]].
+
+If any step fails, the orchestrator compensates the earlier steps (releasing the reservation, voiding the authorization) so the customer is never left in an inconsistent state.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Reserve inventory, authorize payment, create order"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area           | Description                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| Inventory      | Reserves stock via [[command\|reserve-inventory]].                                               |
+| Payment        | Authorizes the order total via [[command\|authorize-payment]].                                   |
+| Order creation | Creates the order via [[command\|create-order]] against the [[system\|order-management-system]]. |
+| Compensation   | Rolls back earlier steps if a later step fails.                                                  |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx

@@ -0,0 +1,39 @@
+---
+id: order-database
+name: Order Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for orders and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for orders
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Order Database** is the authoritative store for orders at Acme Inc. The [[service|order-service]] reads from and writes to it as orders are created, cancelled and completed.
+
+### What does it store?
+
+- **Orders** — one row per order: id, customer, status, total and timestamps.
+- **Order Items** — one row per item in an order: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Order Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Orders are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.