@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CheckoutCart",
+  "description": "Command to check out a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart to check out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "promotionCode": {
+      "description": "Optional promotion code to apply at checkout",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId"]
+}

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx

@@ -0,0 +1,32 @@
+---
+id: remove-item-from-cart
+name: Remove Item From Cart
+version: 1.0.0
+summary: |
+  Command to remove an item from a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /carts/{cartId}/items/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RemoveItemFromCart` is handled by the [[service|cart-api]]. It removes an item from the cart (or decreases its quantity) and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RemoveItemFromCart",
+  "description": "Command to remove an item from a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to remove",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to remove. If omitted, removes the item entirely.",
+      "type": "integer",
+      "minimum": 1
+    }
+  },
+  "required": ["cartId", "productId"]
+}

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx

@@ -0,0 +1,29 @@
+---
+id: cart-checked-out
+name: Cart Checked Out
+version: 1.0.0
+summary: |
+  Published when a customer has checked out their cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CartCheckedOut` is published by the [[service|cart-api]] when a customer checks out. Downstream systems consume this event to create an order, take payment, and begin fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CartCheckedOut",
+  "description": "Emitted when a customer checks out their cart",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "cartId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "description": "Price per unit in minor units (e.g. cents)",
+            "type": "integer"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "subtotal": {
+      "description": "Total before discounts, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "discount": {
+      "description": "Total discount applied, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "total": {
+      "description": "Final total, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["eventId", "occurredAt", "cartId", "customerId", "items", "total", "currency"]
+}

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx

@@ -0,0 +1,72 @@
+---
+id: cart-api
+version: 1.0.0
+name: Cart API
+summary: |
+  The public-facing API for shopping carts. Handles commands to add and remove items and to check out, and publishes an event when a cart is checked out.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - shopping-platform
+receives:
+  - id: add-item-to-cart
+    version: 1.0.0
+  - id: remove-item-from-cart
+    version: 1.0.0
+  - id: checkout-cart
+    version: 1.0.0
+sends:
+  - id: cart-checked-out
+    version: 1.0.0
+  - id: calculate-discount
+    version: 1.0.0
+writesTo:
+  - id: cart-database
+readsFrom:
+  - id: cart-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/cart-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Cart API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Cart API** is the front door to the Cart System. It validates incoming commands, persists cart contents to the [[container|cart-database]], asks the [[system|promotion-system]] to calculate discounts via [[command|calculate-discount]], and publishes a [[event|cart-checked-out]] event when the customer checks out.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Checkout event and discount requests"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Cart commands handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                                                             |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Cart management  | Validates and applies [[command\|add-item-to-cart]], [[command\|remove-item-from-cart]] and [[command\|checkout-cart]]. |
+| Discounts        | Requests pricing from the Promotion System via [[command\|calculate-discount]].                                         |
+| Event publishing | Emits [[event\|cart-checked-out]] when a cart is checked out.                                                           |
+| Persistence      | Reads from and writes to the [[container\|cart-database]] (system of record).                                           |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml

@@ -0,0 +1,200 @@
+openapi: 3.0.3
+info:
+  title: Cart API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Cart System. Customers use it to build a cart —
+    adding and removing items — and to check out. At checkout the cart is priced
+    (including discounts from the Promotion System) and a `CartCheckedOut` event
+    is published.
+  contact:
+    name: Shopping Platform
+    email: shopping-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Cart
+    description: Build and check out a shopping cart.
+paths:
+  /carts/{cartId}/items:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: addItemToCart
+      summary: Add an item to the cart
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AddItemRequest'
+      responses:
+        '200':
+          description: The item was added; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/items/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+      - name: productId
+        in: path
+        required: true
+        description: Identifier of the product to remove.
+        schema:
+          type: string
+          format: uuid
+    delete:
+      operationId: removeItemFromCart
+      summary: Remove an item from the cart
+      tags:
+        - Cart
+      responses:
+        '200':
+          description: The item was removed; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '404':
+          description: The cart or item was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/checkout:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: checkoutCart
+      summary: Check out the cart
+      description: Prices the cart (including discounts) and, on success, publishes a `CartCheckedOut` event.
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CheckoutRequest'
+      responses:
+        '200':
+          description: The cart was checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: The cart is empty or already checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    CartId:
+      name: cartId
+      in: path
+      required: true
+      description: Unique identifier of the cart.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Cart:
+      type: object
+      required: [cartId, status, items, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [OPEN, CHECKED_OUT, ABANDONED]
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+        subtotal:
+          type: integer
+          description: Total before discounts, in minor units (e.g. cents).
+        discount:
+          type: integer
+          description: Total discount applied, in minor units (e.g. cents).
+        total:
+          type: integer
+          description: Final total, in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+    CartItem:
+      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).
+    AddItemRequest:
+      type: object
+      required: [productId, quantity]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+    CheckoutRequest:
+      type: object
+      required: [customerId]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        promotionCode:
+          type: string
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx

@@ -0,0 +1,40 @@
+---
+id: promotion-database
+name: Promotion Database
+version: 1.0.0
+summary: PostgreSQL store of promotion and discount rules.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for promotion and discount rules
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Promotion Database** holds the promotion and discount rules that the [[service|promotion-service]] evaluates when pricing a cart. It is the source of truth for what promotions exist, who they apply to, and when they are valid.
+
+### What does it store?
+
+- **Promotions** — one row per promotion: code, type (percentage / fixed amount), value, and validity window.
+- **Eligibility rules** — the conditions under which a promotion applies (minimum spend, customer segment, etc.).
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Promotion Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|promotion-service]] reads rules when handling [[command|calculate-discount]].
+- Rules are managed by the promotions team and change infrequently relative to read volume.

package/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql

@@ -0,0 +1,21 @@
+-- Promotion Database — system of record for promotion and discount rules
+
+CREATE TABLE promotions (
+    promotion_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    code         TEXT NOT NULL UNIQUE,
+    description  TEXT,
+    type         TEXT NOT NULL CHECK (type IN ('PERCENTAGE', 'FIXED_AMOUNT')),
+    value        INTEGER NOT NULL CHECK (value >= 0),
+    starts_at    TIMESTAMPTZ NOT NULL,
+    ends_at      TIMESTAMPTZ,
+    active       BOOLEAN NOT NULL DEFAULT true
+);
+
+CREATE TABLE eligibility_rules (
+    promotion_id     UUID NOT NULL REFERENCES promotions (promotion_id) ON DELETE CASCADE,
+    min_spend_cents  INTEGER CHECK (min_spend_cents >= 0),
+    customer_segment TEXT,
+    PRIMARY KEY (promotion_id)
+);
+
+CREATE INDEX idx_promotions_active ON promotions (active) WHERE active = true;

package/templates/default/domains/Shopping/systems/promotion-system/index.mdx

@@ -0,0 +1,48 @@
+---
+id: promotion-system
+name: Promotion System
+version: 1.0.0
+summary: |
+  Internal system that calculates the discounts and promotions that apply to a cart. It owns promotion rules and returns calculated discounts to the Cart System.
+owners:
+  - shopping-platform
+services:
+  - id: promotion-service
+containers:
+  - id: promotion-database
+relationships:
+  - id: cart-system
+    label: provides discounts to
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Promotion System** owns the discount and promotion rules at Acme Inc. It receives requests to calculate the discount for a cart, evaluates the applicable rules from the [[container|promotion-database]], and publishes a [[event|discount-calculated]] event with the result. It provides discounts to the [[system|cart-system]].
+
+## 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\|promotion-service]]    | Service    | Evaluates promotion rules and calculates discounts for a cart. |
+| [[container\|promotion-database]] | Data store | PostgreSQL store of promotion and discount rules.              |
+
+## Messages this system publishes
+
+- [[event|discount-calculated]] — a discount has been calculated for a cart.

package/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx

@@ -0,0 +1,32 @@
+---
+id: calculate-discount
+name: Calculate Discount
+version: 1.0.0
+summary: |
+  Command to calculate the discount that applies to a cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /discounts/calculate
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CalculateDiscount` is handled by the [[service|promotion-service]]. It is sent by the [[service|cart-api]] when pricing a cart. The service evaluates the applicable promotion rules and returns the discount, also publishing a [[event|discount-calculated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CalculateDiscount",
+  "description": "Command to calculate the discount for a cart, and the discount returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "cartId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "subtotal": {
+          "description": "Cart subtotal before discounts, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "promotionCode": {
+          "description": "Optional promotion code supplied by the customer",
+          "type": "string"
+        }
+      },
+      "required": ["cartId", "subtotal", "currency"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "discount": {
+          "description": "Total discount to apply, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "appliedPromotions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": ["discount"]
+    }
+  },
+  "required": ["request", "response"]
+}

package/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: discount-calculated
+name: Discount Calculated
+version: 1.0.0
+summary: |
+  Published when a discount has been calculated for a cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DiscountCalculated` is published by the [[service|promotion-service]] after evaluating the promotion rules for a cart. The [[system|cart-system]] uses the result to price the cart, and other systems can consume it for analytics.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />