@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

package/templates/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx

@@ -0,0 +1,39 @@
+---
+id: search-index
+name: Search Index
+version: 1.0.0
+summary: The denormalised, search-optimised index of products that powers product search.
+container_type: searchIndex
+technology: opensearch@2
+authoritative: false
+access_mode: readWrite
+purpose: Serve fast, relevant product search
+classification: internal
+retention: rebuildable
+residency: eu-west-1
+styles:
+  icon: /icons/analytics/clickhouse.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Search Index** is a denormalised, search-optimised copy of the catalog. It is **not** a source of truth — it can be rebuilt at any time by replaying product events from the [[system|product-catalog-system]]. The [[service|search-indexer]] keeps it up to date, and the [[service|search-api]] reads from it to answer [[query|search-products]] queries.
+
+### What does it store?
+
+One document per product, optimised for search:
+
+- Searchable text — name and description, analysed for full-text matching.
+- Filterable fields — category, status, price, currency.
+- A relevance signal used to rank results.
+
+### Why is it not authoritative?
+
+The system of record is the [[container|product-database]]. The index is a derived read model: if it is ever lost or corrupted, we rebuild it by replaying [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events. This keeps search fast without coupling other teams to the catalog database.
+
+### Operational notes
+
+- **Rebuildable**: a full reindex is a supported, routine operation.
+- **Eventually consistent**: changes appear in search shortly after the [[service|search-indexer]] processes the corresponding event.

package/templates/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx

@@ -0,0 +1,130 @@
+---
+id: product-search-indexing
+name: Product Search Indexing
+version: 1.0.0
+summary: |
+  How a change to a product in the catalog reliably flows into the search index — via the outbox, product events and the indexer — so search stays in sync without coupling to the catalog database.
+owners:
+  - search-platform
+steps:
+  - id: merchant_edits_product
+    title: Merchant edits a product
+    actor:
+      name: Merchant
+      summary: A merchant creates or updates a product in the catalog.
+    next_step:
+      id: product_api
+      label: Apply change
+
+  - id: product_api
+    title: Product API
+    service:
+      id: product-api
+      version: 1.0.0
+    next_step:
+      id: product_database
+      label: Write change + outbox row
+
+  - id: product_database
+    title: Product Database
+    container:
+      id: product-database
+    next_step:
+      id: outbox_note
+      label: Outbox row committed
+
+  - id: outbox_note
+    title: Outbox pattern
+    custom:
+      title: Transactional outbox
+      color: blue
+      icon: InboxStackIcon
+      type: Pattern
+      summary: The product change and an outbox row are written in the same transaction, so the event can never be lost or out of sync with the data.
+      properties:
+        guarantee: 'change and event are atomic'
+    next_step:
+      id: product_search_publisher
+      label: Drain outbox
+
+  - id: product_search_publisher
+    title: Product Search Publisher
+    service:
+      id: product-search-publisher
+      version: 1.0.0
+    next_steps:
+      - id: product_created
+        label: Created
+      - id: product_updated
+        label: Updated
+      - id: product_deleted
+        label: Deleted
+
+  - id: product_created
+    title: Product Created
+    message:
+      id: product-created
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Index product
+
+  - id: product_updated
+    title: Product Updated
+    message:
+      id: product-updated
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Re-index product
+
+  - id: product_deleted
+    title: Product Deleted
+    message:
+      id: product-deleted
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Remove from index
+
+  - id: search_indexer
+    title: Search Indexer
+    service:
+      id: search-indexer
+      version: 1.0.0
+    next_step:
+      id: search_index
+      label: Apply to index
+
+  - id: search_index
+    title: Search Index
+    container:
+      id: search-index
+    next_step:
+      id: searchable
+      label: Available to search
+
+  - id: searchable
+    title: Product is searchable
+    custom:
+      title: Product is searchable
+      color: green
+      icon: MagnifyingGlassIcon
+      type: Outcome
+      summary: The change is reflected in the search index and immediately available to customers via the Search API.
+      properties:
+        read_model: 'derived, rebuildable from events'
+---
+
+## Overview
+
+**Product Search Indexing** documents how the [[system|search-system]] keeps its index in sync with the catalog. The search index is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying product events.
+
+<NodeGraph />
+
+## How it works
+
+1. A merchant changes a product via the [[service|product-api]], which writes the change and an outbox row to the [[container|product-database]] in one transaction.
+2. The [[service|product-search-publisher]] reliably drains the outbox and publishes [[event|product-created]], [[event|product-updated]] or [[event|product-deleted]].
+3. The [[service|search-indexer]] consumes those events and applies them to the [[container|search-index]].
+4. The change is now searchable via the Search API — with no direct coupling between search and the catalog database.

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

@@ -0,0 +1,66 @@
+---
+id: search-system
+name: Search System
+version: 1.0.0
+summary: |
+  Internal system that keeps product data searchable. Consumes product change events from the Product Catalog System, maintains a search index, and serves fast product search to the rest of the business.
+owners:
+  - search-platform
+services:
+  - id: search-api
+  - id: search-indexer
+containers:
+  - id: search-index
+flows:
+  - id: product-search-indexing
+    version: 1.0.0
+relationships:
+  - id: product-catalog-system
+    label: indexes product changes from
+actors:
+  - id: shopper
+    name: Shopper
+    label: searches for products
+    direction: inbound
+  - id: storefront-team
+    name: Storefront Team
+    label: integrates product search
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Search System** makes the catalog discoverable. It subscribes to product change events published by the [[system|product-catalog-system]], updates its [[container|search-index]], and exposes a search API so other teams can find products without ever touching the catalog database directly.
+
+## 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\|search-api]]     | Service    | Public-facing API. Serves product search queries from the index.      |
+| [[service\|search-indexer]] | Service    | Consumes product change events and keeps the search index up to date. |
+| [[container\|search-index]] | Data store | The index that powers product search.                                 |
+
+## Messages this system consumes
+
+The Search System reacts to product changes published by the Product Catalog System:
+
+- [[event|product-created]] — index the new product.
+- [[event|product-updated]] — re-index the changed product.
+- [[event|product-deleted]] — remove the product from the index.

package/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx

@@ -0,0 +1,44 @@
+---
+id: search-api
+version: 1.0.0
+name: Search API
+summary: |
+  Public-facing API that serves fast, relevant product search to the rest of the business, reading from the search index.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - search-platform
+receives:
+  - id: search-products
+    version: 1.0.0
+readsFrom:
+  - id: search-index
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/search-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Search API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search API** is the front door to the Search System. It answers [[query|search-products]] queries by reading from the [[container|search-index]], which is kept current by the [[service|search-indexer]]. Other teams use this API so they never have to query the catalog database directly.
+
+### Responsibilities
+
+| Area   | Description                                                                          |
+| ------ | ------------------------------------------------------------------------------------ |
+| Search | Serves [[query\|search-products]] with full-text matching, filtering and pagination. |
+| Reads  | Queries the [[container\|search-index]] — never the catalog database.                |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />