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

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductCreated",
+  "description": "Emitted when a new product is added to the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was created",
+      "type": "string",
+      "format": "date-time"
+    },
+    "product": {
+      "description": "The product that was created",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier for the product",
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "description": "Stock keeping unit",
+          "type": "string"
+        },
+        "name": {
+          "description": "Display name of the product",
+          "type": "string"
+        },
+        "description": {
+          "description": "Long-form product description",
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "description": "Category the product belongs to",
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "product"]
+}

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx

@@ -0,0 +1,29 @@
+---
+id: product-deleted
+name: Product Deleted
+version: 1.0.0
+summary: |
+  Published when a product has been removed from the catalog.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductDeleted` is published by the [[service|product-search-publisher]] when a product is removed from the catalog via the [[service|product-api]]. The [[system|search-system]] consumes this event to remove the product from the search index.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductDeleted",
+  "description": "Emitted when a product is removed from the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was deleted",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that was deleted",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product was removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId"]
+}

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: product-updated
+name: Product Updated
+version: 1.0.0
+summary: |
+  Published when an existing product's data has changed.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductUpdated` is published by the [[service|product-search-publisher]] whenever an existing product is changed via the [[service|product-api]]. The [[system|search-system]] consumes this event to re-index the product so search results stay accurate.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductUpdated",
+  "description": "Emitted when an existing product's data changes",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was updated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that changed",
+      "type": "string",
+      "format": "uuid"
+    },
+    "changes": {
+      "description": "The fields that changed and their new values",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "minProperties": 1
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId", "changes"]
+}

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx

@@ -0,0 +1,69 @@
+---
+id: product-api
+version: 1.0.0
+name: Product API
+summary: |
+  The public-facing API for the product catalog. Handles commands to create, update and delete products, serves product reads, and is the entry point into the Product Catalog System.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - product-platform
+receives:
+  - id: create-product
+    version: 1.0.0
+  - id: update-product
+    version: 1.0.0
+  - id: delete-product
+    version: 1.0.0
+  - id: get-product
+    version: 1.0.0
+writesTo:
+  - id: product-database
+readsFrom:
+  - id: product-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/product-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Product API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product API** is the front door to the Product Catalog System. It validates incoming commands, persists product data to the [[container|product-database]], and records every change to the outbox. The [[service|product-search-publisher]] then turns those changes into the domain events the rest of the business consumes.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Commands and queries handled by this service"
+  />
+  <Tile
+    icon="CircleStackIcon"
+    href="/docs/services/product-api/1.0.0"
+    title="System of record"
+    description="Reads from and writes to the product database"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Command handling | Validates and applies [[command\|create-product]], [[command\|update-product]] and [[command\|delete-product]].                             |
+| Reads            | Serves [[query\|get-product]] directly from the product database.                                                                           |
+| Change capture   | Records every product change to the outbox in the [[container\|product-database]] for the [[service\|product-search-publisher]] to publish. |
+| Persistence      | Reads from and writes to the [[container\|product-database]] (system of record).                                                            |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml

@@ -0,0 +1,219 @@
+openapi: 3.0.3
+info:
+  title: Product API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Product Catalog System. It is the entry point for
+    creating, updating, deleting and reading products. Every change is persisted
+    to the product database and recorded in the outbox so product change events
+    can be published to the rest of the business.
+  contact:
+    name: Product Platform
+    email: product-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Products
+    description: Manage and read products in the catalog.
+paths:
+  /products:
+    post:
+      operationId: createProduct
+      summary: Create a product
+      description: Adds a new product to the catalog. On success a `ProductCreated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateProductRequest'
+      responses:
+        '201':
+          description: The product was created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A product with the same SKU already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /products/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/ProductId'
+    get:
+      operationId: getProduct
+      summary: Get a product
+      description: Returns the current state of a single product by its identifier.
+      tags:
+        - Products
+      responses:
+        '200':
+          description: The product was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateProduct
+      summary: Update a product
+      description: Applies a partial update to an existing product. On success a `ProductUpdated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateProductRequest'
+      responses:
+        '200':
+          description: The product was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    delete:
+      operationId: deleteProduct
+      summary: Delete a product
+      description: Removes a product from the catalog. On success a `ProductDeleted` event is published.
+      tags:
+        - Products
+      parameters:
+        - name: reason
+          in: query
+          required: false
+          description: Optional reason the product is being removed.
+          schema:
+            type: string
+            enum: [DISCONTINUED, DUPLICATE, MERCHANT_REQUEST, OTHER]
+      responses:
+        '204':
+          description: The product was deleted.
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    ProductId:
+      name: productId
+      in: path
+      required: true
+      description: Unique identifier of the product.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Product:
+      type: object
+      required: [productId, sku, name, price, currency, status]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+          description: Stock keeping unit.
+        name:
+          type: string
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    CreateProductRequest:
+      type: object
+      required: [sku, name, price, currency]
+      properties:
+        sku:
+          type: string
+          description: Stock keeping unit — must be unique.
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          description: Initial lifecycle status — defaults to DRAFT.
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    UpdateProductRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx

@@ -0,0 +1,32 @@
+---
+id: get-product
+name: Get Product
+version: 1.0.0
+summary: |
+  Query to fetch a single product by its identifier.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /products/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProduct` is handled by the [[service|product-api]]. It returns the current state of a single product, read directly from the [[container|product-database]]. Use the [[system|search-system]] when you need to search across many products instead.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProduct",
+  "description": "Query to fetch a single product by its identifier, and the product returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the product",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier of the product to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "description": "The product returned by the query",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer"
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx

@@ -0,0 +1,56 @@
+---
+id: product-search-publisher
+version: 1.0.0
+name: Product Search Publisher
+summary: |
+  Reads product changes from the product database (outbox) and reliably publishes product-created, product-updated and product-deleted events for the Search System to consume.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+sends:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-search-publisher'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Search Publisher** is the bridge between the Product Catalog System and the rest of the business. It uses the [transactional outbox pattern](https://microservices.io/patterns/data/transactional-outbox.html): the [[service|product-api]] records every product change in the [[container|product-database]], and this service reliably reads those changes and publishes them as [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+This guarantees that product changes are never lost and are delivered to the [[system|search-system]] in order.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Product change events published for downstream systems"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area                | Description                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Outbox polling      | Reads unpublished product changes from the [[container\|product-database]].                                                  |
+| Reliable publishing | Publishes [[event\|product-created]], [[event\|product-updated]] and [[event\|product-deleted]] with at-least-once delivery. |
+| Ordering            | Preserves per-product ordering of change events.                                                                             |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />

package/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx

@@ -0,0 +1,48 @@
+---
+id: product-worker
+version: 1.0.0
+name: Product Worker
+summary: |
+  Background worker that handles long-running and asynchronous catalog work off the request path, such as enrichment, image processing and bulk imports.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+writesTo:
+  - id: product-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Worker** keeps the [[service|product-api]] fast by taking slow or asynchronous work off the request path. It reads from and writes back to the [[container|product-database]], handling jobs like data enrichment, image processing and bulk catalog imports.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title="View in visualiser"
+    description="See how the Product Worker fits into the system"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area         | Description                                                                   |
+| ------------ | ----------------------------------------------------------------------------- |
+| Enrichment   | Augments product records with derived data after they are created or updated. |
+| Media        | Processes and optimises product images asynchronously.                        |
+| Bulk imports | Ingests large product feeds without blocking the API.                         |
+| Persistence  | Reads from and writes to the [[container\|product-database]].                 |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />