@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

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

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CancelOrder",
+  "description": "Command to cancel an existing order",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "description": "Identifier of the order to cancel",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Why the order is being cancelled",
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    }
+  },
+  "required": ["orderId", "reason"]
+}

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

@@ -0,0 +1,32 @@
+---
+id: create-order
+name: Create Order
+version: 1.0.0
+summary: |
+  Command to create a new order from a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateOrder` is sent by the [[service|checkout-orchestrator]] and handled by the [[service|order-service]]. It is the final step of the checkout saga — once inventory is reserved and payment is authorized, this command creates the order. On success the Order Service publishes an [[event|order-created]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateOrder",
+  "description": "Command to create a new order from a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart this order was created from",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer placing the order",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items in the order",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "type": "integer",
+            "description": "Price per unit in minor units (e.g. cents)"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "total": {
+      "description": "Order total in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "paymentAuthorizationId": {
+      "description": "Identifier of the payment authorization for this order",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId", "items", "total", "currency"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: order-cancelled
+name: Order Cancelled
+version: 1.0.0
+summary: |
+  Published when an order has been cancelled.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCancelled` is published by the [[service|order-service]] when an order is cancelled — whether at the customer's request or because a downstream step (payment, inventory) failed. Downstream systems consume it to release inventory, refund or void payment, and stop fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCancelled",
+  "description": "Published when an order has been cancelled",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    },
+    "cancelledAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "reason", "cancelledAt"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: order-completed
+name: Order Completed
+version: 1.0.0
+summary: |
+  Published when an order has been fulfilled and completed.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCompleted` is published by the [[service|order-service]] when an order has been fully fulfilled. It marks the end of the happy path for an order. Downstream systems consume it to close out fulfilment, capture payment, and update reporting.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCompleted",
+  "description": "Published when an order has been fulfilled and completed",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "completedAt"]
+}