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

package/templates/default/domains/Catalog/entities/product-variant/index.mdx

@@ -0,0 +1,35 @@
+---
+id: product-variant
+name: Product Variant
+version: 1.0.0
+identifier: variantId
+summary: A purchasable variation of a product, such as size or color.
+owners:
+  - product-platform
+properties:
+  - name: variantId
+    type: UUID
+    required: true
+    description: Unique variant identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product this variant belongs to.
+    references: product
+    relationType: belongsTo
+    referencesIdentifier: productId
+  - name: sku
+    type: string
+    required: true
+    description: Variant-level SKU.
+  - name: attributes
+    type: object
+    required: true
+    description: Variant dimensions such as size, color or material.
+---
+
+## Overview
+
+Product Variant captures the concrete option a customer can buy. It belongs to a [[entity|product]] and is indexed into search when product data changes.
+
+<EntityPropertiesTable />

package/templates/default/domains/Catalog/entities/search-document/index.mdx

@@ -0,0 +1,35 @@
+---
+id: search-document
+name: Search Document
+version: 1.0.0
+identifier: documentId
+summary: The denormalized representation of product data indexed by Search.
+owners:
+  - search-platform
+properties:
+  - name: documentId
+    type: string
+    required: true
+    description: Search index document identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product represented by the document.
+    references: product
+    relationType: represents
+    referencesIdentifier: productId
+  - name: searchableText
+    type: string
+    required: true
+    description: Text used for matching and ranking.
+  - name: indexedAt
+    type: datetime
+    required: true
+    description: Time the document was last indexed.
+---
+
+## Overview
+
+Search Document is the read model maintained by [[system|search-system]]. It is eventually consistent with the Product Catalog System.
+
+<EntityPropertiesTable />

package/templates/default/domains/Catalog/index.mdx

@@ -0,0 +1,65 @@
+---
+id: catalog
+name: Catalog
+version: 1.0.0
+summary: |
+  The Catalog domain owns everything about products — how they are created, maintained and made discoverable across Acme Inc. It is the source of truth for product data and powers product search across the business.
+owners:
+  - product-platform
+systems:
+  - id: product-catalog-system
+    version: 1.0.0
+  - id: search-system
+    version: 1.0.0
+entities:
+  - id: product
+    version: 1.0.0
+  - id: product-variant
+    version: 1.0.0
+  - id: category
+    version: 1.0.0
+  - id: search-document
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Catalog** domain is responsible for the lifecycle of every product Acme Inc sells, and for making those products discoverable. It is split into two internal systems that work together:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/product-catalog-system/1.0.0"
+    title="Product Catalog System"
+    description="System of record for product data — create, update, delete and read products."
+  />
+  <Tile
+    icon="MagnifyingGlassIcon"
+    href="/docs/systems/search-system/1.0.0"
+    title="Search System"
+    description="Indexes product changes and serves fast, relevant product search to the rest of the business."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Product Catalog System** is the authoritative source of product data. Whenever a product is created, updated or deleted it publishes a domain event. The **Search System** subscribes to those events, keeps its search index in sync, and exposes a search API so other teams never have to query the catalog database directly.
+
+The diagram below shows the domain's systems, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Component map
+
+These are the components that are part of this domain (parts of the systems in this domain)
+
+<NodeGraph />

package/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx

@@ -0,0 +1,43 @@
+---
+id: adr-001-use-transactional-outbox
+name: 'ADR-001: Publish product events via a transactional outbox'
+summary: Product change events are written to an outbox table in the same transaction as the change, then relayed to the broker, so an event is never lost or published for a rolled-back change.
+version: 1.0.0
+status: accepted
+date: 2026-02-10
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-search-publisher
+  - type: container
+    id: product-database
+badges:
+  - content: Messaging
+    backgroundColor: blue
+    textColor: blue
+  - content: Reliability
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+The Product Catalog System is the source of truth for products, and other systems — notably the [[system|search-system]] — depend on a reliable stream of `product-created`, `product-updated` and `product-deleted` events. Publishing to the broker directly from the [[service|product-api]] request path creates a dual-write problem: if the database commit succeeds but the broker publish fails (or vice versa), the catalog and its consumers drift out of sync. Lost or phantom events are hard to detect and expensive to reconcile.
+
+## Decision
+
+The Product API writes every product change **and** a corresponding row in an `outbox` table inside a single database transaction in the [[container|product-database]]. A separate relay, the [[service|product-search-publisher]], reads unpublished outbox rows in order and publishes them to the broker with at-least-once delivery, marking each row published once acknowledged.
+
+This decouples persistence from publishing: the request path only touches the database, and event delivery becomes an independent, retryable concern.
+
+## Consequences
+
+- Events are never lost and never published for a change that rolled back — the change and its event share a transaction boundary.
+- Consumers must be **idempotent**, since at-least-once delivery means an event can be redelivered.
+- There is a small publish latency between the commit and the relay draining the outbox.
+- The outbox table needs a retention/cleanup policy so it doesn't grow unbounded.

package/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx

@@ -0,0 +1,40 @@
+---
+id: adr-002-postgres-as-system-of-record
+name: 'ADR-002: Use PostgreSQL as the product system of record'
+summary: Product data is stored in a single PostgreSQL database that acts as the authoritative system of record, with derived stores (like the search index) rebuilt from it.
+version: 1.0.0
+status: accepted
+date: 2026-02-12
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: container
+    id: product-database
+related:
+  - id: adr-001-use-transactional-outbox
+badges:
+  - content: Data
+    backgroundColor: purple
+    textColor: purple
+---
+
+## Context
+
+Products are a small-to-medium, strongly relational dataset (products, categories, pricing, lifecycle status) that needs transactional integrity, an enforceable schema, and the ability to write a change and its outbox event atomically. We also want a single, unambiguous source of truth so that derived stores — such as the [[system|search-system]]'s index — can be treated as disposable and rebuilt at any time.
+
+## Decision
+
+The Product Catalog System uses a single **PostgreSQL** database, the [[container|product-database]], as the authoritative system of record. It holds the `products` table and the outbox table (see [[adr|adr-001-use-transactional-outbox]]). The [[service|product-api]] is the only writer on the request path; the [[service|product-worker]] performs asynchronous enrichment.
+
+Any other representation of product data elsewhere in the business is a **derived read model**, not a source of truth, and must be rebuildable by replaying product events.
+
+## Consequences
+
+- Strong consistency and transactional outbox writes are straightforward with a single relational store.
+- The search index and any future read models can be rebuilt from the catalog, keeping them disposable.
+- The database is a scaling focal point; heavy read traffic should be served from read replicas or downstream read models rather than the primary.
+- Schema changes need migrations and care, since this is the authoritative store.

package/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx

@@ -0,0 +1,41 @@
+---
+id: adr-003-offload-async-work-to-worker
+name: 'ADR-003: Offload long-running catalog work to a dedicated worker'
+summary: Slow and asynchronous catalog tasks (enrichment, image processing, bulk imports) run in a separate Product Worker so the Product API stays fast and predictable.
+version: 1.0.0
+status: accepted
+date: 2026-02-18
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-worker
+  - type: service
+    id: product-api
+badges:
+  - content: Architecture
+    backgroundColor: blue
+    textColor: blue
+  - content: Performance
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+Some catalog operations are slow or bursty: enriching products with derived attributes, processing and optimising images, and ingesting large supplier feeds. Running this work inline in the [[service|product-api]] request path would make API latency unpredictable and couple the responsiveness of create/update/read operations to whatever heavy job happens to be running.
+
+## Decision
+
+The Product Catalog System runs a dedicated [[service|product-worker]] for long-running and asynchronous tasks. The [[service|product-api]] handles validation, persistence and the outbox write synchronously, then returns; the worker picks up enrichment, media processing and bulk imports independently, reading from and writing back to the [[container|product-database]].
+
+## Consequences
+
+- The Product API has a small, predictable surface and stays fast under load.
+- Heavy work can be scaled, retried and scheduled independently of the API.
+- Some product attributes are **eventually** populated after creation, so consumers must not assume every derived field is present immediately.
+- There are now two services writing to the [[container|product-database]], so write paths must respect the same invariants and avoid conflicting updates.

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

@@ -0,0 +1,45 @@
+---
+id: product-database
+name: Product Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all product data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for products, plus the change outbox used to publish events
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Product Database** is the authoritative store for every product in the catalog. The [[service|product-api]] reads from and writes to it, and the [[service|product-worker]] uses it for asynchronous enrichment. It also holds the **outbox** table that the [[service|product-search-publisher]] reads to publish product change events.
+
+### What does it store?
+
+- **Products** — one row per product: SKU, name, description, price, currency, category and lifecycle status.
+- **Outbox** — one row per product change, used to reliably publish [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Product Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|product-api]] is the only writer to the `products` table on the request path.
+- The [[service|product-search-publisher]] is a read-only consumer of the `outbox` table.
+- The [[service|product-worker]] reads and writes for asynchronous enrichment jobs.
+
+### Why an outbox?
+
+Writing the product change and the event in the **same transaction** guarantees we never persist a change without an event, or publish an event for a change that rolled back. The publisher reads the outbox and emits events with at-least-once delivery.

package/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql

@@ -0,0 +1,33 @@
+-- Product Database — system of record for the product catalog
+
+CREATE TABLE products (
+    product_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    sku          TEXT NOT NULL UNIQUE,
+    name         TEXT NOT NULL,
+    description  TEXT,
+    price_cents  INTEGER NOT NULL CHECK (price_cents >= 0),
+    currency     CHAR(3) NOT NULL,
+    category     TEXT,
+    status       TEXT NOT NULL DEFAULT 'DRAFT'
+                   CHECK (status IN ('DRAFT', 'ACTIVE', 'ARCHIVED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_products_category ON products (category);
+CREATE INDEX idx_products_status   ON products (status);
+
+-- Transactional outbox — change events are written here in the same
+-- transaction as the product change, then drained by the Product Search Publisher.
+CREATE TABLE outbox (
+    id            BIGSERIAL PRIMARY KEY,
+    product_id    UUID NOT NULL REFERENCES products (product_id),
+    event_type    TEXT NOT NULL
+                    CHECK (event_type IN ('ProductCreated', 'ProductUpdated', 'ProductDeleted')),
+    payload       JSONB NOT NULL,
+    occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    published_at  TIMESTAMPTZ
+);
+
+-- Index used by the publisher to find unpublished changes in order.
+CREATE INDEX idx_outbox_unpublished ON outbox (id) WHERE published_at IS NULL;

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