@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

@@ -0,0 +1,72 @@
+---
+id: product-catalog-system
+name: Product Catalog System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for product data. Owns the product database and publishes product change events for the rest of the business to consume.
+owners:
+  - product-platform
+services:
+  - id: product-api
+  - id: product-worker
+  - id: product-search-publisher
+containers:
+  - id: product-database
+relationships:
+  - id: search-system
+    label: notifies of product changes
+actors:
+  - id: merchandiser
+    name: Merchandiser
+    label: creates and updates products
+    direction: inbound
+  - id: catalog-admin
+    name: Catalog Admin
+    label: manages categories and pricing
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Product Catalog System** is the system of record for products at Acme Inc. It accepts commands to create, update and delete products, persists them in the [[container|product-database]], and emits domain events whenever product data changes so downstream systems — like the [[system|search-system]] — can react.
+
+## 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.
+
+<ComponentDiagram />
+
+## What's inside
+
+| Component                             | Type       | Responsibility                                                              |
+| ------------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| [[service\|product-api]]              | Service    | Public-facing API. Handles create/update/delete commands and product reads. |
+| [[service\|product-worker]]           | Service    | Processes long-running and asynchronous catalog work off the request path.  |
+| [[service\|product-search-publisher]] | Service    | Publishes product change events for the Search System to consume.           |
+| [[container\|product-database]]       | Data store | PostgreSQL system of record for all product data.                           |
+
+## Messages this system publishes
+
+When product data changes, the system emits these events:
+
+- [[event|product-created]] — a new product has been added to the catalog.
+- [[event|product-updated]] — an existing product's data has changed.
+- [[event|product-deleted]] — a product has been removed from the catalog.
+- [[adr|adr-001-use-transactional-outbox]] — a product has been removed from the catalog.
+
+## Architecture decisions
+
+The key decisions that shaped this system. Search, filter by status, or sort by clicking a column.
+
+<ADRTable />

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

@@ -0,0 +1,32 @@
+---
+id: create-product
+name: Create Product
+version: 1.0.0
+summary: |
+  Command to add a new product to the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /products
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateProduct` is handled by the [[service|product-api]]. It validates the incoming product, writes it to the [[container|product-database]], and on success publishes a [[event|product-created]] event.
+
+## 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/commands/CreateProduct/schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateProduct",
+  "description": "Command to add a new product to the catalog",
+  "type": "object",
+  "properties": {
+    "sku": {
+      "description": "Stock keeping unit — must be unique",
+      "type": "string"
+    },
+    "name": {
+      "description": "Display name of the product",
+      "type": "string",
+      "minLength": 1
+    },
+    "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": "Initial lifecycle status — defaults to DRAFT",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["sku", "name", "price", "currency"]
+}

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

@@ -0,0 +1,32 @@
+---
+id: delete-product
+name: Delete Product
+version: 1.0.0
+summary: |
+  Command to remove a product from the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /products/{productId}
+  statusCodes: ['204', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DeleteProduct` is handled by the [[service|product-api]]. It removes a product from the [[container|product-database]] and, on success, publishes a [[event|product-deleted]] event so downstream systems can clean up.
+
+## 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/commands/DeleteProduct/schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DeleteProduct",
+  "description": "Command to remove a product from the catalog",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to delete",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product is being removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["productId"]
+}

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

@@ -0,0 +1,32 @@
+---
+id: update-product
+name: Update Product
+version: 1.0.0
+summary: |
+  Command to update an existing product in the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: PATCH
+  path: /products/{productId}
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'PATCH'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`UpdateProduct` is handled by the [[service|product-api]]. It applies a partial update to an existing product in the [[container|product-database]] and, on success, publishes a [[event|product-updated]] event describing what changed.
+
+## 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/commands/UpdateProduct/schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UpdateProduct",
+  "description": "Command to update an existing product. Only the fields supplied are changed.",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to update",
+      "type": "string",
+      "format": "uuid"
+    },
+    "name": {
+      "description": "New display name",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "New long-form description",
+      "type": "string"
+    },
+    "price": {
+      "description": "New 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": "New category",
+      "type": "string"
+    },
+    "status": {
+      "description": "New lifecycle status",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["productId"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: product-created
+name: Product Created
+version: 1.0.0
+summary: |
+  Published when a new product has been added to 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
+
+`ProductCreated` is published by the [[service|product-search-publisher]] whenever a new product is successfully added to the catalog by the [[service|product-api]]. The [[system|search-system]] consumes this event to index the new product so it becomes discoverable.
+
+<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/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 />