@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

package/templates/default/domains/Customer/entities/authentication-session/index.mdx

@@ -0,0 +1,35 @@
+---
+id: authentication-session
+name: Authentication Session
+version: 1.0.0
+identifier: sessionId
+summary: A successful customer authentication session.
+owners:
+  - customer-platform
+properties:
+  - name: sessionId
+    type: UUID
+    required: true
+    description: Unique authentication session identifier.
+  - name: accountId
+    type: UUID
+    required: true
+    description: Account authenticated in the session.
+    references: customer-account
+    relationType: belongsTo
+    referencesIdentifier: accountId
+  - name: authenticatedAt
+    type: datetime
+    required: true
+    description: Time authentication succeeded.
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the session expires.
+---
+
+## Overview
+
+Authentication Session represents successful login behavior emitted by [[event|customer-authenticated]].
+
+<EntityPropertiesTable />

package/templates/default/domains/Customer/entities/customer-account/index.mdx

@@ -0,0 +1,36 @@
+---
+id: customer-account
+name: Customer Account
+version: 1.0.0
+identifier: accountId
+aggregateRoot: true
+summary: The identity account used to authenticate a customer.
+owners:
+  - customer-platform
+properties:
+  - name: accountId
+    type: UUID
+    required: true
+    description: Unique account identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer profile linked to this account.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: provider
+    type: string
+    required: true
+    description: Identity provider name.
+  - name: status
+    type: string
+    required: true
+    description: Account lifecycle state.
+---
+
+## Overview
+
+Customer Account belongs to the Identity Provider boundary and should not be queried directly by order, payment or review services.
+
+<EntityPropertiesTable />

package/templates/default/domains/Customer/entities/customer-address/index.mdx

@@ -0,0 +1,35 @@
+---
+id: customer-address
+name: Customer Address
+version: 1.0.0
+identifier: addressId
+summary: A saved address attached to a customer profile.
+owners:
+  - customer-platform
+properties:
+  - name: addressId
+    type: UUID
+    required: true
+    description: Unique address identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who owns the address.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: countryCode
+    type: string
+    required: true
+    description: ISO country code.
+  - name: postalCode
+    type: string
+    required: true
+    description: Postal or ZIP code.
+---
+
+## Overview
+
+Customer Address supports checkout and fulfilment while remaining owned by the Customer domain.
+
+<EntityPropertiesTable />

package/templates/default/domains/Customer/entities/customer-profile/index.mdx

@@ -0,0 +1,33 @@
+---
+id: customer-profile
+name: Customer Profile
+version: 1.0.0
+identifier: customerId
+aggregateRoot: true
+summary: The customer details Acme uses for commerce interactions.
+owners:
+  - customer-platform
+properties:
+  - name: customerId
+    type: UUID
+    required: true
+    description: Unique customer identifier.
+  - name: email
+    type: string
+    required: true
+    description: Customer email address.
+  - name: displayName
+    type: string
+    required: false
+    description: Preferred customer display name.
+  - name: status
+    type: string
+    required: true
+    description: Customer profile state.
+---
+
+## Overview
+
+Customer Profile is owned by [[system|customer-management-system]] and is separate from authentication credentials.
+
+<EntityPropertiesTable />

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

@@ -0,0 +1,67 @@
+---
+id: customer
+name: Customer
+version: 1.0.0
+summary: |
+  The Customer domain owns who our customers are — how they register, how their profile is maintained, and how they are authenticated across Acme Inc. It is the source of truth for customer identity and profile data.
+owners:
+  - customer-platform
+systems:
+  - id: customer-management-system
+    version: 1.0.0
+  - id: identity-provider
+    version: 1.0.0
+entities:
+  - id: customer-profile
+    version: 1.0.0
+  - id: customer-account
+    version: 1.0.0
+  - id: authentication-session
+    version: 1.0.0
+  - id: customer-address
+    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 **Customer** domain is responsible for the lifecycle of every customer account at Acme Inc — registration, profile updates, and authentication. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/customer-management-system/1.0.0"
+    title="Customer Management System"
+    description="System of record for customer profiles — register, update and read customers."
+  />
+  <Tile
+    icon="LockClosedIcon"
+    href="/docs/systems/identity-provider/1.0.0"
+    title="Identity Provider"
+    description="Authenticates customers and is the source of truth for credentials and login."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Customer Management System** owns customer profile data — it accepts registration and update commands and publishes events when customers change. The **Identity Provider** handles authentication: it verifies credentials and emits an event when a customer successfully authenticates, which the rest of the business can react to.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />

package/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx

@@ -0,0 +1,43 @@
+---
+id: customer-database
+name: Customer Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all customer profile data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for customer profiles
+classification: confidential
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Customer Database** is the authoritative store for every customer profile at Acme Inc. The [[service|customer-api]] reads from and writes to it. It stores profile data only — credentials and authentication live in the [[system|identity-provider]]'s [[container|user-directory]], not here.
+
+### What does it store?
+
+- **Customers** — one row per customer: id, email, name and account status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Customer Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|customer-api]] is the only writer on the request path.
+- No credentials or passwords are stored here — only profile data. Authentication is owned by the [[system|identity-provider]].
+
+### Classification
+
+Customer profile data is **confidential**. Access is role-based and least-privilege; PII handling follows Acme's data policies.

package/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql

@@ -0,0 +1,14 @@
+-- Customer Database — system of record for customer profiles
+-- Note: credentials/authentication are owned by the Identity Provider, not stored here.
+
+CREATE TABLE customers (
+    customer_id  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email        TEXT NOT NULL UNIQUE,
+    name         TEXT,
+    status       TEXT NOT NULL DEFAULT 'ACTIVE'
+                   CHECK (status IN ('ACTIVE', 'SUSPENDED', 'CLOSED')),
+    registered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_customers_status ON customers (status);