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

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

package/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml

@@ -0,0 +1,138 @@
+openapi: 3.0.3
+info:
+  title: Search API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Search System. Serves fast, relevant product
+    search by reading from the search index, which is kept in sync with the
+    product catalog.
+  contact:
+    name: Search Platform
+    email: search-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+paths:
+  /search/products:
+    get:
+      operationId: searchProducts
+      summary: Search the catalog for products
+      description: |
+        Runs a full-text search over the product index and returns a paginated
+        list of matching products. Supports optional filters and pagination.
+      tags:
+        - Search
+      parameters:
+        - name: query
+          in: query
+          required: true
+          description: Free-text search term.
+          schema:
+            type: string
+            minLength: 1
+          example: wireless headphones
+        - name: category
+          in: query
+          required: false
+          description: Restrict results to a single category.
+          schema:
+            type: string
+          example: audio
+        - name: status
+          in: query
+          required: false
+          description: Restrict results to products with this lifecycle status.
+          schema:
+            type: string
+            enum: [DRAFT, ACTIVE, ARCHIVED]
+        - name: minPrice
+          in: query
+          required: false
+          description: Minimum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: maxPrice
+          in: query
+          required: false
+          description: Maximum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: page
+          in: query
+          required: false
+          description: 1-based page number.
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          required: false
+          description: Number of results per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: A paginated list of matching products.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResults'
+        '400':
+          description: The request was invalid (e.g. a missing or empty query).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    SearchResults:
+      type: object
+      required: [total, page, pageSize, results]
+      properties:
+        total:
+          type: integer
+          description: Total number of products matching the query.
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ProductSearchResult'
+    ProductSearchResult:
+      type: object
+      required: [productId, sku, name]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        score:
+          type: number
+          description: Relevance score for this result.
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

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

@@ -0,0 +1,32 @@
+---
+id: search-products
+name: Search Products
+version: 1.0.0
+summary: |
+  Query to search the catalog for products matching a term, with optional filters and pagination.
+owners:
+  - search-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /search/products
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SearchProducts` is handled by the [[service|search-api]]. It runs a full-text search over the [[container|search-index]] and returns a paginated list of matching products. Use this whenever you need to find products across the catalog, rather than fetching a single product by id with [[query|get-product]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SearchProducts",
+  "description": "Query to search the catalog for products, and the paginated result returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Search parameters",
+      "type": "object",
+      "properties": {
+        "query": {
+          "description": "Free-text search term",
+          "type": "string",
+          "minLength": 1
+        },
+        "filters": {
+          "description": "Optional filters applied to the search",
+          "type": "object",
+          "properties": {
+            "category": {
+              "type": "string"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+            },
+            "minPrice": {
+              "description": "Minimum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            },
+            "maxPrice": {
+              "description": "Maximum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "page": {
+          "description": "1-based page number",
+          "type": "integer",
+          "minimum": 1,
+          "default": 1
+        },
+        "pageSize": {
+          "description": "Number of results per page",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 20
+        }
+      },
+      "required": ["query"]
+    },
+    "response": {
+      "description": "Paginated search results",
+      "type": "object",
+      "properties": {
+        "total": {
+          "description": "Total number of products matching the query",
+          "type": "integer"
+        },
+        "page": {
+          "type": "integer"
+        },
+        "pageSize": {
+          "type": "integer"
+        },
+        "results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": {
+                "type": "string",
+                "format": "uuid"
+              },
+              "sku": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "category": {
+                "type": "string"
+              },
+              "price": {
+                "description": "Price in minor units (e.g. cents)",
+                "type": "integer"
+              },
+              "currency": {
+                "type": "string",
+                "pattern": "^[A-Z]{3}$"
+              },
+              "score": {
+                "description": "Relevance score for this result",
+                "type": "number"
+              }
+            },
+            "required": ["productId", "sku", "name"]
+          }
+        }
+      },
+      "required": ["total", "page", "pageSize", "results"]
+    }
+  },
+  "required": ["request", "response"]
+}

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

@@ -0,0 +1,54 @@
+---
+id: search-indexer
+version: 1.0.0
+name: Search Indexer
+summary: |
+  Consumes product change events from the Product Catalog System and keeps the search index up to date so products are discoverable.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - search-platform
+receives:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+writesTo:
+  - id: search-index
+repository:
+  language: Go
+  url: 'https://github.com/acme/search-indexer'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search Indexer** is how the Search System stays in sync with the catalog. It subscribes to [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events published by the [[system|product-catalog-system]] and applies each change to the [[container|search-index]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Product change events consumed from the catalog"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Event                      | Action                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| [[event\|product-created]] | Add the new product to the [[container\|search-index]]. |
+| [[event\|product-updated]] | Re-index the changed product.                           |
+| [[event\|product-deleted]] | Remove the product from the index.                      |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />

package/templates/default/domains/Catalog/ubiquitous-language.mdx

@@ -0,0 +1,54 @@
+---
+dictionary:
+  - id: Product
+    name: Product
+    summary: 'A single item Acme Inc sells, with a name, price, category and lifecycle status.'
+    description: |
+      A product is the central concept of the Catalog domain. It is owned and maintained by the
+      Product Catalog System, which is the source of truth for all product data. A product carries:
+
+      - A unique product id and a unique SKU
+      - Display name, description and category
+      - Price (in minor units) and currency
+      - A lifecycle status (DRAFT, ACTIVE or ARCHIVED)
+
+      Every change to a product publishes a domain event so the rest of the business — including
+      search — can react.
+    icon: Package
+  - id: SKU
+    name: SKU
+    summary: 'Stock Keeping Unit — the unique, human-meaningful code that identifies a product.'
+    description: |
+      A SKU uniquely identifies a product in the catalog and must be unique across all products.
+      Unlike the internal product id (a UUID), the SKU is the code teams and merchants use day to day.
+    icon: Tag
+  - id: Catalog
+    name: Catalog
+    summary: 'The complete, authoritative collection of products Acme Inc offers.'
+    icon: BookOpen
+  - id: Search Index
+    name: Search Index
+    summary: 'A denormalised, search-optimised copy of the catalog that powers product search.'
+    description: |
+      The search index is a derived read model, not a source of truth. It is kept in sync by the
+      Search System consuming product change events, and can be rebuilt at any time by replaying
+      those events. It exists to serve fast, relevant search without coupling consumers to the
+      catalog database.
+    icon: Search
+  - id: Lifecycle Status
+    name: Lifecycle Status
+    summary: 'Where a product sits in its life: DRAFT, ACTIVE or ARCHIVED.'
+    description: |
+      - DRAFT — being prepared, not yet visible to customers.
+      - ACTIVE — live and discoverable.
+      - ARCHIVED — withdrawn from sale but retained for history.
+    icon: Workflow
+  - id: Outbox
+    name: Outbox
+    summary: 'A table where product changes are recorded in the same transaction, then published as events.'
+    description: |
+      The outbox is how the Product Catalog System guarantees that a product change and its event
+      are never out of sync. The Product API writes the change and an outbox row in one transaction;
+      the Product Search Publisher reliably drains the outbox to the broker.
+    icon: Mail
+---