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

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.

package/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql

@@ -0,0 +1,24 @@
+-- Order Database — system of record for orders
+
+CREATE TABLE orders (
+    order_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    cart_id      UUID,
+    customer_id  UUID NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'CREATED'
+                   CHECK (status IN ('CREATED', 'COMPLETED', 'CANCELLED')),
+    total_cents  INTEGER NOT NULL CHECK (total_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE order_items (
+    order_id         UUID NOT NULL REFERENCES orders (order_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (order_id, product_id)
+);
+
+CREATE INDEX idx_orders_customer ON orders (customer_id);
+CREATE INDEX idx_orders_status   ON orders (status);

package/templates/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx

@@ -0,0 +1,105 @@
+---
+id: order-cancellation
+name: Order Cancellation
+version: 1.0.0
+summary: |
+  How an order is cancelled — whether requested by the customer or triggered by a failure — and the events that tell the rest of the business to unwind it.
+owners:
+  - ordering-platform
+steps:
+  - id: cancellation_trigger
+    title: Cancellation requested
+    actor:
+      name: Shopper or System
+      summary: A customer asks to cancel, or a downstream failure (payment, inventory) forces a cancellation.
+    next_step:
+      id: cancel_order_command
+      label: Cancel order
+
+  - id: cancel_order_command
+    title: Cancel Order
+    message:
+      id: cancel-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Handle cancellation
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_steps:
+      - id: eligibility_check
+        label: Check eligibility
+      - id: not_cancellable
+        label: Already completed
+
+  - id: eligibility_check
+    title: Cancellation policy check
+    custom:
+      title: Cancellation policy
+      color: blue
+      icon: ClipboardDocumentCheckIcon
+      type: Policy
+      summary: An order can only be cancelled before it is completed. Completed orders must go through returns instead.
+      properties:
+        rule: 'status must be CREATED'
+    next_step:
+      id: order_database
+      label: Mark cancelled
+
+  - id: order_database
+    title: Order Database
+    container:
+      id: order-database
+    next_step:
+      id: order_cancelled
+      label: Persist + publish
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+    next_step:
+      id: downstream_unwind
+      label: Unwind downstream
+
+  - id: downstream_unwind
+    title: Downstream unwind
+    custom:
+      title: Release and refund
+      color: orange
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: Consumers of OrderCancelled release reserved inventory, void or refund the payment, and stop fulfilment.
+      properties:
+        consumers: 'inventory, payment, fulfilment'
+
+  - id: not_cancellable
+    title: Cannot cancel
+    custom:
+      title: Cannot cancel
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: The order has already been completed and cannot be cancelled. The customer is directed to the returns process.
+      properties:
+        next_action: 'start a return'
+---
+
+## Overview
+
+**Order Cancellation** documents how the [[system|order-management-system]] cancels an order. Cancellation can be requested by a shopper or forced by a downstream failure during checkout. Only orders that have not yet completed can be cancelled.
+
+<NodeGraph />
+
+## How it works
+
+1. A [[command|cancel-order]] command reaches the [[service|order-service]].
+2. The service checks the cancellation policy — only `CREATED` orders are cancellable.
+3. If eligible, the order is marked cancelled in the [[container|order-database]] and [[event|order-cancelled]] is published.
+4. Downstream consumers react to [[event|order-cancelled]] to release inventory, refund payment and stop fulfilment.
+5. If the order is already completed, cancellation is rejected and the customer is sent to the returns process.

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

@@ -0,0 +1,53 @@
+---
+id: order-management-system
+name: Order Management System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for orders. It creates orders, tracks their lifecycle, and publishes events as orders are created, completed and cancelled.
+owners:
+  - ordering-platform
+services:
+  - id: order-service
+containers:
+  - id: order-database
+flows:
+  - id: order-cancellation
+    version: 1.0.0
+relationships:
+  - id: checkout-system
+    label: receives orders from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Order Management System** owns the order at Acme Inc. It accepts the [[command|create-order]] command from the [[system|checkout-system]], persists orders in the [[container|order-database]], and serves order lookups via [[query|get-order]]. As an order moves through its lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events for the rest of the business to react to.
+
+## 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\|order-service]]    | Service    | Creates, cancels and serves orders, and publishes order lifecycle events. |
+| [[container\|order-database]] | Data store | PostgreSQL system of record for orders and their items.                   |
+
+## Messages this system publishes
+
+- [[event\|order-created]] — a new order has been created.
+- [[event\|order-completed]] — an order has been fulfilled and completed.
+- [[event\|order-cancelled]] — an order has been cancelled.

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml

@@ -0,0 +1,233 @@
+asyncapi: 3.0.0
+
+info:
+  title: Order Service
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Order Service — the system of record for orders.
+
+    The service consumes commands to create and cancel orders, and publishes events as
+    orders move through their lifecycle (created, completed, cancelled). Query access
+    (`GetOrder`) is served over the REST API and is not part of this AsyncAPI document.
+  contact:
+    name: Ordering Platform
+    email: ordering-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  orderCommands:
+    address: ordering.commands
+    title: Order commands
+    description: Commands the Order Service consumes to create and cancel orders.
+    messages:
+      CreateOrder:
+        $ref: '#/components/messages/CreateOrder'
+      CancelOrder:
+        $ref: '#/components/messages/CancelOrder'
+
+  orderEvents:
+    address: ordering.orders
+    title: Order lifecycle events
+    description: Events the Order Service publishes as orders move through their lifecycle.
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+      OrderCompleted:
+        $ref: '#/components/messages/OrderCompleted'
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+operations:
+  receiveCreateOrder:
+    action: receive
+    title: Create Order
+    summary: Create a new order from a checked-out cart.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CreateOrder'
+
+  receiveCancelOrder:
+    action: receive
+    title: Cancel Order
+    summary: Cancel an existing order.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CancelOrder'
+
+  publishOrderCreated:
+    action: send
+    title: Order Created
+    summary: Published when a new order has been created.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCreated'
+
+  publishOrderCompleted:
+    action: send
+    title: Order Completed
+    summary: Published when an order has been fulfilled and completed.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCompleted'
+
+  publishOrderCancelled:
+    action: send
+    title: Order Cancelled
+    summary: Published when an order has been cancelled.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCancelled'
+
+components:
+  messages:
+    CreateOrder:
+      name: CreateOrder
+      title: Create Order
+      summary: Command to create a new order from a checked-out cart.
+      payload:
+        $ref: '#/components/schemas/CreateOrder'
+    CancelOrder:
+      name: CancelOrder
+      title: Cancel Order
+      summary: Command to cancel an existing order.
+      payload:
+        $ref: '#/components/schemas/CancelOrder'
+    OrderCreated:
+      name: OrderCreated
+      title: Order Created
+      summary: Published when a new order has been created.
+      payload:
+        $ref: '#/components/schemas/OrderCreated'
+    OrderCompleted:
+      name: OrderCompleted
+      title: Order Completed
+      summary: Published when an order has been fulfilled and completed.
+      payload:
+        $ref: '#/components/schemas/OrderCompleted'
+    OrderCancelled:
+      name: OrderCancelled
+      title: Order Cancelled
+      summary: Published when an order has been cancelled.
+      payload:
+        $ref: '#/components/schemas/OrderCancelled'
+
+  schemas:
+    OrderItem:
+      type: object
+      required: [productId, quantity, unitPrice]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+        unitPrice:
+          type: integer
+          description: Price per unit in minor units (e.g. cents).
+
+    CancellationReason:
+      type: string
+      enum: [CUSTOMER_REQUESTED, PAYMENT_FAILED, OUT_OF_STOCK, FRAUD]
+
+    CreateOrder:
+      type: object
+      description: Command to create a new order from a checked-out cart.
+      required: [cartId, customerId, items, total, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderItem'
+        total:
+          type: integer
+          minimum: 0
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        paymentAuthorizationId:
+          type: string
+          description: Identifier of the payment authorization for this order.
+
+    CancelOrder:
+      type: object
+      description: Command to cancel an existing order.
+      required: [orderId, reason]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+
+    OrderCreated:
+      type: object
+      description: Published when a new order has been created.
+      required: [orderId, customerId, total, currency, createdAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        total:
+          type: integer
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        createdAt:
+          type: string
+          format: date-time
+
+    OrderCompleted:
+      type: object
+      description: Published when an order has been fulfilled and completed.
+      required: [orderId, customerId, completedAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        completedAt:
+          type: string
+          format: date-time
+
+    OrderCancelled:
+      type: object
+      description: Published when an order has been cancelled.
+      required: [orderId, reason, cancelledAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+        cancelledAt:
+          type: string
+          format: date-time

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx

@@ -0,0 +1,32 @@
+---
+id: cancel-order
+name: Cancel Order
+version: 1.0.0
+summary: |
+  Command to cancel an existing order.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders/{orderId}/cancel
+  statusCodes: ['200', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CancelOrder` is handled by the [[service|order-service]]. It cancels an order that has not yet been completed — releasing any reservations and voiding the payment authorization where needed. On success the Order Service publishes an [[event|order-cancelled]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />