@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

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

@@ -0,0 +1,69 @@
+---
+id: payments
+name: Payments
+version: 1.0.0
+summary: |
+  The Payments domain takes payment for orders and processes refunds. It orchestrates authorization and capture through an external payment processor, and screens payments for fraud.
+owners:
+  - payments-platform
+systems:
+  - id: payment-processing-system
+    version: 1.0.0
+  - id: stripe
+    version: 1.0.0
+  - id: fraud-detection
+    version: 1.0.0
+entities:
+  - id: payment
+    version: 1.0.0
+  - id: payment-authorization
+    version: 1.0.0
+  - id: refund
+    version: 1.0.0
+  - id: fraud-check
+    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 **Payments** domain is responsible for moving money. It authorizes and captures payment for orders, issues refunds, and screens payments for fraud. It owns one internal system and integrates with two external providers:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/payment-processing-system/1.0.0"
+    title="Payment Processing System"
+    description="Orchestrates authorization, capture and refunds for orders."
+  />
+  <Tile
+    icon="BuildingLibraryIcon"
+    href="/docs/systems/stripe/1.0.0"
+    title="Stripe"
+    description="External payment processor that charges cards and issues refunds."
+  />
+  <Tile
+    icon="ShieldExclamationIcon"
+    href="/docs/systems/fraud-detection/1.0.0"
+    title="Fraud Detection"
+    description="External provider that screens payments for fraud."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Payment Processing System** is the internal orchestrator. When the Ordering domain authorizes a payment, it requests payment via the external **Stripe** system and, in parallel, asks **Fraud Detection** to screen the payment. Stripe reports back whether the payment succeeded or failed, and the Payment Processing System records the outcome.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />

package/templates/default/domains/Payments/systems/fraud-detection/index.mdx

@@ -0,0 +1,49 @@
+---
+id: fraud-detection
+name: Fraud Detection
+version: 1.0.0
+scope: external
+summary: |
+  External provider that screens payments for fraud. It consumes payment requests and returns a pass or fail verdict.
+owners:
+  - payments-platform
+services:
+  - id: fraud-api
+relationships:
+  - id: payment-processing-system
+    label: screens payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+**Fraud Detection** is an external provider Acme Inc uses to screen payments for fraud. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+It consumes [[event|payment-requested]] and returns a verdict via [[event|fraud-check-passed]] or [[event|fraud-check-failed]].
+
+## 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\|fraud-api]] | Service | Screens a payment for fraud and returns a pass/fail verdict. |
+
+## Messages this system publishes
+
+- [[event\|fraud-check-passed]] — a payment passed fraud screening.
+- [[event\|fraud-check-failed]] — a payment failed fraud screening.

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx

@@ -0,0 +1,29 @@
+---
+id: fraud-check-failed
+name: Fraud Check Failed
+version: 1.0.0
+summary: |
+  Published when a payment fails fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckFailed` is published by the [[service|fraud-api]] when a payment is flagged as fraudulent. The [[system|payment-processing-system]] uses it to block the charge and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckFailed",
+  "description": "Published when a payment fails fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; higher is riskier"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["HIGH_RISK_SCORE", "BLOCKLISTED", "VELOCITY", "MISMATCH"]
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "checkedAt"]
+}

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx

@@ -0,0 +1,29 @@
+---
+id: fraud-check-passed
+name: Fraud Check Passed
+version: 1.0.0
+summary: |
+  Published when a payment passes fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckPassed` is published by the [[service|fraud-api]] when a payment clears fraud screening. The [[system|payment-processing-system]] uses it to allow the charge to proceed.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckPassed",
+  "description": "Published when a payment passes fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; lower is safer"
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "checkedAt"]
+}