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

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"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: order-created
+name: Order Created
+version: 1.0.0
+summary: |
+  Published when a new order has been created.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCreated` is published by the [[service|order-service]] when a new order is created from a checked-out cart. Downstream systems consume this event to begin fulfilment, send confirmation to the customer, 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/OrderCreated/schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCreated",
+  "description": "Published when a new order has been created",
+  "type": "object",
+  "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"
+    }
+  },
+  "required": ["orderId", "customerId", "total", "currency", "createdAt"]
+}

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

@@ -0,0 +1,74 @@
+---
+id: order-service
+version: 1.0.0
+name: Order Service
+summary: |
+  The system of record for orders. Creates and cancels orders, serves order lookups, and publishes events as orders move through their lifecycle.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - ordering-platform
+receives:
+  - id: create-order
+    version: 1.0.0
+  - id: cancel-order
+    version: 1.0.0
+  - id: get-order
+    version: 1.0.0
+sends:
+  - id: order-created
+    version: 1.0.0
+  - id: order-completed
+    version: 1.0.0
+  - id: order-cancelled
+    version: 1.0.0
+writesTo:
+  - id: order-database
+readsFrom:
+  - id: order-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/order-service'
+specifications:
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Order Service AsyncAPI
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Order Service** is the heart of the Order Management System. It receives [[command|create-order]] from the [[system|checkout-system]], persists orders to the [[container|order-database]], and serves order lookups via [[query|get-order]]. It also handles [[command|cancel-order]]. As orders move through their lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Order lifecycle events"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Order commands and queries"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area               | Description                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| Order creation     | Handles [[command\|create-order]] from the Checkout System and persists the order.         |
+| Order cancellation | Handles [[command\|cancel-order]] and compensates downstream where needed.                 |
+| Order lookups      | Serves [[query\|get-order]] from the [[container\|order-database]].                        |
+| Event publishing   | Emits [[event\|order-created]], [[event\|order-completed]] and [[event\|order-cancelled]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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

@@ -0,0 +1,32 @@
+---
+id: get-order
+name: Get Order
+version: 1.0.0
+summary: |
+  Query to fetch a single order by its identifier.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /orders/{orderId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetOrder` is handled by the [[service|order-service]]. It returns the current state of a single order, read directly from the [[container|order-database]].
+
+## 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/queries/GetOrder/schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetOrder",
+  "description": "Query to fetch a single order by its identifier, and the order returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the order",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "description": "Unique identifier of the order to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["orderId"]
+    },
+    "response": {
+      "description": "The order returned by the query",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["CREATED", "COMPLETED", "CANCELLED"]
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": { "type": "string", "format": "uuid" },
+              "quantity": { "type": "integer", "minimum": 1 },
+              "unitPrice": { "type": "integer" }
+            },
+            "required": ["productId", "quantity", "unitPrice"]
+          }
+        },
+        "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"
+        }
+      },
+      "required": ["orderId", "customerId", "status", "items", "total", "currency"]
+    }
+  },
+  "required": ["request", "response"]
+}

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

@@ -0,0 +1,53 @@
+---
+dictionary:
+  - id: Order
+    name: Order
+    summary: 'A confirmed intent to purchase, created from a checked-out cart and owned for its whole lifecycle.'
+    description: |
+      The order is the central concept of the Ordering domain. It is owned by the Order Management
+      System, which is the source of truth for orders. An order has:
+
+      - A unique order id and the customer it belongs to
+      - A set of order items (product, quantity and unit price)
+      - A total and currency
+      - A status (CREATED, COMPLETED or CANCELLED)
+
+      An order is immutable in its essentials once created — its lifecycle is expressed through events,
+      not by editing it in place.
+    icon: ClipboardList
+  - id: Checkout
+    name: Checkout
+    summary: 'The flow that turns a checked-out cart into a confirmed order.'
+    description: |
+      Checkout is owned by the Checkout System. It is the orchestration that runs after the Shopping
+      domain checks out a cart — reserving inventory, authorizing payment and creating the order.
+    icon: CreditCard
+  - id: Saga
+    name: Saga
+    summary: 'A multi-step process with compensating actions, used to coordinate checkout across systems.'
+    description: |
+      The Checkout Orchestrator runs checkout as a saga: a sequence of steps (reserve inventory,
+      authorize payment, create order) where each step has a compensating action that undoes it if a
+      later step fails. This keeps the customer consistent without distributed transactions.
+    icon: Workflow
+  - id: Reservation
+    name: Reservation
+    summary: 'A temporary hold on stock for the items in a cart, taken during checkout.'
+    icon: PackageCheck
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method for the order total, captured when the order is created."
+    icon: ShieldCheck
+  - id: Order Item
+    name: Order Item
+    summary: 'A single product line within an order: a product, a quantity and the price paid per unit.'
+    icon: ListOrdered
+  - id: Order Status
+    name: Order Status
+    summary: 'Where an order sits in its life: CREATED, COMPLETED or CANCELLED.'
+    description: |
+      - CREATED — the order exists and is being fulfilled.
+      - COMPLETED — the order has been fully fulfilled.
+      - CANCELLED — the order was cancelled before completion.
+    icon: Workflow
+---

package/templates/default/domains/Payments/entities/fraud-check/index.mdx

@@ -0,0 +1,39 @@
+---
+id: fraud-check
+name: Fraud Check
+version: 1.0.0
+identifier: fraudCheckId
+summary: Fraud screening result associated with a payment attempt.
+owners:
+  - payments-platform
+properties:
+  - name: fraudCheckId
+    type: UUID
+    required: true
+    description: Unique fraud check identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment attempt being screened.
+    references: payment
+    relationType: screens
+    referencesIdentifier: paymentId
+  - name: result
+    type: string
+    required: true
+    description: Screening result.
+    enum:
+      - passed
+      - failed
+      - review
+  - name: checkedAt
+    type: datetime
+    required: true
+    description: Time screening completed.
+---
+
+## Overview
+
+Fraud Check documents the screening outcome from [[system|fraud-detection]] so payment decisions are auditable.
+
+<EntityPropertiesTable />

package/templates/default/domains/Payments/entities/payment/index.mdx

@@ -0,0 +1,36 @@
+---
+id: payment
+name: Payment
+version: 1.0.0
+identifier: paymentId
+aggregateRoot: true
+summary: Acme's internal record of payment intent and outcome for an order.
+owners:
+  - payments-platform
+properties:
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Unique payment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being paid for.
+    references: order
+    relationType: paysFor
+    referencesIdentifier: orderId
+  - name: amount
+    type: decimal
+    required: true
+    description: Amount requested.
+  - name: status
+    type: string
+    required: true
+    description: Payment lifecycle status.
+---
+
+## Overview
+
+Payment is the Payments domain aggregate. It records Acme's view of payment state regardless of external provider retries or webhook order.
+
+<EntityPropertiesTable />

package/templates/default/domains/Payments/entities/payment-authorization/index.mdx

@@ -0,0 +1,35 @@
+---
+id: payment-authorization
+name: Payment Authorization
+version: 1.0.0
+identifier: authorizationId
+summary: Approval from a payment provider to reserve funds for an order.
+owners:
+  - payments-platform
+properties:
+  - name: authorizationId
+    type: UUID
+    required: true
+    description: Unique authorization identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment this authorization belongs to.
+    references: payment
+    relationType: belongsTo
+    referencesIdentifier: paymentId
+  - name: providerReference
+    type: string
+    required: true
+    description: External payment provider reference.
+  - name: authorizedAt
+    type: datetime
+    required: true
+    description: Time authorization was granted.
+---
+
+## Overview
+
+Payment Authorization captures the result of [[command|authorize-payment]] and links Acme payment state to provider state.
+
+<EntityPropertiesTable />

package/templates/default/domains/Payments/entities/refund/index.mdx

@@ -0,0 +1,36 @@
+---
+id: refund
+name: Refund
+version: 1.0.0
+identifier: refundId
+aggregateRoot: true
+summary: A request to return money to a customer after payment.
+owners:
+  - payments-platform
+properties:
+  - name: refundId
+    type: UUID
+    required: true
+    description: Unique refund identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment being refunded.
+    references: payment
+    relationType: refunds
+    referencesIdentifier: paymentId
+  - name: amount
+    type: decimal
+    required: true
+    description: Refund amount.
+  - name: status
+    type: string
+    required: true
+    description: Refund lifecycle state.
+---
+
+## Overview
+
+Refund is owned by Payments and records refund requests and provider outcomes such as [[event|refund-processed]].
+
+<EntityPropertiesTable />