@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

package/dist/index.js

@@ -29808,7 +29808,7 @@ var import_os2 = __toESM(require("os"));
 var package_default = {
   name: "@eventcatalog/create-eventcatalog",
   description: "Create EventCatalog with one command",
-  version: "4.3.3",
+  version: "4.3.4",
   license: "MIT",
   bin: {
     "create-catalog": "./dist/index.js"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eventcatalog/create-eventcatalog",
   "description": "Create EventCatalog with one command",
-  "version": "4.3.3",
+  "version": "4.3.4",
   "license": "MIT",
   "bin": {
     "create-catalog": "./dist/index.js"

package/templates/default/README-template.md

@@ -19,8 +19,9 @@ Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file
 Good places to start:
 
 - `domains/` - bounded contexts, business capabilities, and ownership
-- `domains/<domain>/services/` - services, APIs, and message producers or consumers
-- `events/`, `commands/`, and `queries/` - the messages flowing through your system
+- `domains/<domain>/systems/` - systems and containers inside each domain
+- `domains/<domain>/systems/<system>/services/` - services, APIs, and message producers or consumers
+- `commands/`, `events/`, and `queries/` folders under services - the messages flowing through your system
 - `teams/` and `users/` - who owns each part of the architecture
 
 Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.

package/templates/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:03:00.194Z",
+  "resourceKey": "domains-systems-context/catalog/1.0.0",
+  "positions": {
+    "product-catalog-system-1.0.0": {
+      "x": 654.4139077853363,
+      "y": 77.21012849584278
+    },
+    "search-system-1.0.0": {
+      "x": 1145,
+      "y": 335
+    },
+    "actor-merchandiser": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-catalog-admin": {
+      "x": 90,
+      "y": 260
+    },
+    "actor-shopper": {
+      "x": 595,
+      "y": 360
+    },
+    "actor-storefront-team": {
+      "x": 595,
+      "y": 560
+    }
+  }
+}

package/templates/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-26T12:15:29.856Z",
+  "resourceKey": "domains-systems-context/customer/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 652.3279365079366,
+      "y": 338.73238095238094
+    },
+    "identity-provider-1.0.0": {
+      "x": 745.6812698412698,
+      "y": 71.1025396825397
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 122.5
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 322.5
+    }
+  }
+}

package/templates/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json

@@ -0,0 +1,91 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T08:55:18.430Z",
+  "resourceKey": "system-context-map/system-context-map/1.0.0",
+  "positions": {
+    "carrier-1.0.0": {
+      "x": 1423.6053719008264,
+      "y": 1259.6570247933885
+    },
+    "shipping-system-1.0.0": {
+      "x": 1622.4194214876034,
+      "y": 1702.4814049586778
+    },
+    "cart-system-1.0.0": {
+      "x": 595,
+      "y": 60
+    },
+    "promotion-system-1.0.0": {
+      "x": 1145,
+      "y": 60
+    },
+    "actor-shopper": {
+      "x": 56.553719008264444,
+      "y": 178.41322314049586
+    },
+    "checkout-system-1.0.0": {
+      "x": 595,
+      "y": 260
+    },
+    "order-management-system-1.0.0": {
+      "x": 1145,
+      "y": 260
+    },
+    "customer-management-system-1.0.0": {
+      "x": 812.667132867133,
+      "y": 836.9146853146854
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 1085
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 910
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 1110
+    },
+    "fraud-detection-1.0.0": {
+      "x": -664.9235537190083,
+      "y": 1282.7169421487602
+    },
+    "payment-processing-system-1.0.0": {
+      "x": -145.58264462809922,
+      "y": 1486.1818181818182
+    },
+    "inventory-system-1.0.0": {
+      "x": 366.3367768595041,
+      "y": 1716.0785123966941
+    },
+    "warehouse-system-1.0.0": {
+      "x": 955.3574380165288,
+      "y": 1529.3367768595042
+    },
+    "stripe-1.0.0": {
+      "x": 318.0144628099173,
+      "y": 1260.4194214876034
+    },
+    "product-catalog-system-1.0.0": {
+      "x": 1145,
+      "y": 497.5
+    },
+    "search-system-1.0.0": {
+      "x": 440.8853146853147,
+      "y": 723.5524475524476
+    },
+    "actor-merchandiser": {
+      "x": 447.2405594405594,
+      "y": 530.0979020979021
+    },
+    "actor-catalog-admin": {
+      "x": 561.634965034965,
+      "y": 418.6909090909091
+    },
+    "actor-storefront-team": {
+      "x": -349.5522886204704,
+      "y": 775.1666878575969
+    }
+  }
+}

package/templates/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:26:03.901Z",
+  "resourceKey": "systems-context/customer-management-system/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 593.5226571767497,
+      "y": -13.867141162514821
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 85
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 260
+    }
+  }
+}

package/templates/default/components/footer.astro

@@ -5,4 +5,3 @@ import config from '@config';
 <div class="w-full text-right">
   <span class="italic text-[rgb(var(--ec-page-text-muted))]">Event-driven architecture documentation: {config.organizationName}</span>
 </div>
-

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

@@ -0,0 +1,36 @@
+---
+id: category
+name: Category
+version: 1.0.0
+identifier: categoryId
+aggregateRoot: true
+summary: A merchandising grouping used to organize products for discovery.
+owners:
+  - product-platform
+properties:
+  - name: categoryId
+    type: UUID
+    required: true
+    description: Unique category identifier.
+  - name: slug
+    type: string
+    required: true
+    description: Stable URL-safe category key.
+  - name: displayName
+    type: string
+    required: true
+    description: Customer-facing category name.
+  - name: parentCategoryId
+    type: UUID
+    required: false
+    description: Parent category for hierarchy navigation.
+    references: category
+    relationType: belongsTo
+    referencesIdentifier: categoryId
+---
+
+## Overview
+
+Category defines how products are grouped for browsing. It is owned by the Catalog domain and projected into the Search System for discovery.
+
+<EntityPropertiesTable />

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

@@ -0,0 +1,37 @@
+---
+id: product
+name: Product
+version: 1.0.0
+identifier: productId
+aggregateRoot: true
+summary: The sellable item Acme manages in the product catalog.
+owners:
+  - product-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Unique product identifier.
+  - name: sku
+    type: string
+    required: true
+    description: Primary merchandising SKU.
+  - name: name
+    type: string
+    required: true
+    description: Customer-facing product name.
+  - name: status
+    type: string
+    required: true
+    description: Product publication state.
+    enum:
+      - draft
+      - active
+      - archived
+---
+
+## Overview
+
+The Product is the Catalog domain's core aggregate. It is created and maintained by [[service|product-api]] and published to downstream consumers through product events.
+
+<EntityPropertiesTable />

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;