@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

package/templates/default/domains/Reviews/services/ReviewAPI/index.mdx

@@ -0,0 +1,58 @@
+---
+id: review-api
+version: 1.0.0
+name: Review API
+summary: |
+  The public-facing API for product reviews. Accepts review submissions, serves published reviews, and is the entry point into the Reviews & Ratings domain.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: submit-review
+    version: 1.0.0
+  - id: flag-review
+    version: 1.0.0
+  - id: vote-review-helpful
+    version: 1.0.0
+  - id: get-product-reviews
+    version: 1.0.0
+sends:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review API** is the front door to the Reviews & Ratings domain. It validates incoming [[command|submit-review]] commands, persists reviews to the [[container|review-database]], and publishes [[event|review-submitted]]. It also serves [[query|get-product-reviews]], reading published reviews from the [[container|review-database]] and aggregate ratings from the [[container|rating-cache]].
+
+### Responsibilities
+
+| Area             | Description                                                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Command handling | Validates and applies [[command\|submit-review]].                                                                            |
+| Reads            | Serves [[query\|get-product-reviews]] from the review database and rating cache.                                             |
+| Eventing         | Publishes [[event\|review-submitted]] for moderation.                                                                        |
+| Persistence      | Writes to the [[container\|review-database]]; reads from the [[container\|review-database]] and [[container\|rating-cache]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx

@@ -0,0 +1,24 @@
+---
+id: get-product-reviews
+name: Get Product Reviews
+version: 1.0.0
+summary: |
+  Query to fetch the published reviews and aggregate rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProductReviews` is served by the [[service|review-api]]. It returns the published reviews for a product along with its aggregate rating, read from the [[container|review-database]] and the [[container|rating-cache]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProductReviews",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string", "description": "The product to fetch reviews for." },
+    "page": { "type": "integer", "minimum": 1, "default": 1 },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+    "sort": { "type": "string", "enum": ["newest", "highest", "lowest", "most_helpful"], "default": "newest" }
+  },
+  "required": ["productId"]
+}

package/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx

@@ -0,0 +1,29 @@
+---
+id: review-published
+name: Review Published
+version: 1.0.0
+summary: |
+  Published when a submitted review passes moderation and becomes visible on the storefront.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewPublished` is published by the [[service|review-moderation-worker]] when a review passes moderation. The [[service|rating-aggregator]] consumes it to update the product's aggregate rating.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewPublished",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "customerId": { "type": "string" },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "rating", "publishedAt"]
+}

package/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx

@@ -0,0 +1,29 @@
+---
+id: review-rejected
+name: Review Rejected
+version: 1.0.0
+summary: |
+  Published when a submitted review fails moderation (spam, abuse or policy violation) and will not be shown.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewRejected` is published by the [[service|review-moderation-worker]] when a review fails moderation. The review is kept for audit but never published to the storefront.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewRejected",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "policy_violation"] },
+    "rejectedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "reason", "rejectedAt"]
+}

package/templates/default/domains/Reviews/services/ReviewModerationWorker/index.mdx

@@ -0,0 +1,50 @@
+---
+id: review-moderation-worker
+version: 1.0.0
+name: Review Moderation Worker
+summary: |
+  Asynchronous worker that screens submitted reviews for spam, abuse and policy violations, then publishes or rejects them.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+sends:
+  - id: review-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-moderation-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review Moderation Worker** consumes [[event|review-submitted]] (and [[event|review-flagged]] for already-published reviews), screens each review (automated checks plus thresholds for manual review), and records the outcome on the [[container|review-database]]. It then publishes either [[event|review-published]] or [[event|review-rejected]].
+
+### Responsibilities
+
+| Area        | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| Moderation  | Screens reviews for spam, abuse and policy violations.                 |
+| Outcome     | Publishes [[event\|review-published]] or [[event\|review-rejected]].   |
+| Persistence | Records the moderation decision on the [[container\|review-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Shopping/entities/cart/index.mdx

@@ -0,0 +1,40 @@
+---
+id: cart
+name: Cart
+version: 1.0.0
+identifier: cartId
+aggregateRoot: true
+summary: The customer's active collection of items before an order exists.
+owners:
+  - shopping-platform
+properties:
+  - name: cartId
+    type: UUID
+    required: true
+    description: Unique cart identifier.
+  - name: customerId
+    type: UUID
+    required: false
+    description: Customer that owns the cart, if authenticated.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current cart state.
+    enum:
+      - active
+      - checked-out
+      - abandoned
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the cart last changed.
+---
+
+## Overview
+
+Cart is the Shopping domain aggregate. It accepts item changes and emits [[event|cart-checked-out]] when the customer commits to buy.
+
+<EntityPropertiesTable />

package/templates/default/domains/Shopping/entities/cart-item/index.mdx

@@ -0,0 +1,38 @@
+---
+id: cart-item
+name: Cart Item
+version: 1.0.0
+identifier: cartItemId
+summary: A product variant and quantity inside a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: cartItemId
+    type: UUID
+    required: true
+    description: Unique cart item identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart this item belongs to.
+    references: cart
+    relationType: belongsTo
+    referencesIdentifier: cartId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product selected by the customer.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity requested.
+---
+
+## Overview
+
+Cart Item records the customer's intent to buy a product variant before checkout. It is owned by [[entity|cart]].
+
+<EntityPropertiesTable />

package/templates/default/domains/Shopping/entities/discount/index.mdx

@@ -0,0 +1,35 @@
+---
+id: discount
+name: Discount
+version: 1.0.0
+identifier: discountId
+summary: The calculated benefit applied to a cart or cart item.
+owners:
+  - shopping-platform
+properties:
+  - name: discountId
+    type: UUID
+    required: true
+    description: Unique discount identifier.
+  - name: promotionId
+    type: UUID
+    required: false
+    description: Promotion that produced the discount.
+    references: promotion
+    relationType: derivedFrom
+    referencesIdentifier: promotionId
+  - name: amount
+    type: decimal
+    required: true
+    description: Monetary value of the discount.
+  - name: reason
+    type: string
+    required: true
+    description: Human-readable explanation for the discount.
+---
+
+## Overview
+
+Discount is a calculated result from [[command|calculate-discount]]. It is separate from cart persistence so promotion logic can evolve independently.
+
+<EntityPropertiesTable />

package/templates/default/domains/Shopping/entities/promotion/index.mdx

@@ -0,0 +1,40 @@
+---
+id: promotion
+name: Promotion
+version: 1.0.0
+identifier: promotionId
+aggregateRoot: true
+summary: A commercial offer evaluated against a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: promotionId
+    type: UUID
+    required: true
+    description: Unique promotion identifier.
+  - name: code
+    type: string
+    required: false
+    description: Optional customer-entered promotion code.
+  - name: categoryId
+    type: UUID
+    required: false
+    description: Category the promotion applies to when scoped.
+    references: category
+    relationType: appliesTo
+    referencesIdentifier: categoryId
+  - name: status
+    type: string
+    required: true
+    description: Promotion lifecycle state.
+  - name: startsAt
+    type: datetime
+    required: true
+    description: When the promotion becomes active.
+---
+
+## Overview
+
+Promotion is owned by the Promotion System and is evaluated when Shopping calculates discounts for a cart.
+
+<EntityPropertiesTable />

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

@@ -0,0 +1,67 @@
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+summary: |
+  The Shopping domain owns the customer's path to purchase — building a cart, applying promotions, and checking out. It coordinates the cart and the discounts that apply to it.
+owners:
+  - shopping-platform
+systems:
+  - id: cart-system
+    version: 1.0.0
+  - id: promotion-system
+    version: 1.0.0
+entities:
+  - id: cart
+    version: 1.0.0
+  - id: cart-item
+    version: 1.0.0
+  - id: promotion
+    version: 1.0.0
+  - id: discount
+    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 **Shopping** domain is responsible for everything between browsing and buying — the shopping cart and the promotions applied to it. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="ShoppingCartIcon"
+    href="/docs/systems/cart-system/1.0.0"
+    title="Cart System"
+    description="System of record for shopping carts — add, remove and check out items."
+  />
+  <Tile
+    icon="TagIcon"
+    href="/docs/systems/promotion-system/1.0.0"
+    title="Promotion System"
+    description="Calculates the discounts and promotions that apply to a cart."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Cart System** owns the customer's cart and the checkout flow. When pricing a cart, it asks the **Promotion System** to calculate the discounts that apply. When the customer checks out, the Cart System publishes an event the rest of the business reacts 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/Shopping/systems/cart-system/containers/cart-database/index.mdx

@@ -0,0 +1,39 @@
+---
+id: cart-database
+name: Cart Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for shopping carts and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for shopping carts
+classification: internal
+retention: 90d
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Cart Database** is the authoritative store for shopping carts at Acme Inc. The [[service|cart-api]] reads from and writes to it as customers add, remove and check out items.
+
+### What does it store?
+
+- **Carts** — one row per cart: id, customer, status and timestamps.
+- **Cart Items** — one row per item in a cart: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Cart Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Carts are transient. Abandoned carts are pruned after **90 days** (see frontmatter). A checked-out cart's contents live on in the [[event|cart-checked-out]] event and downstream order records.

package/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql

@@ -0,0 +1,22 @@
+-- Cart Database — system of record for shopping carts
+
+CREATE TABLE carts (
+    cart_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    customer_id  UUID,
+    status       TEXT NOT NULL DEFAULT 'OPEN'
+                   CHECK (status IN ('OPEN', 'CHECKED_OUT', 'ABANDONED')),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE cart_items (
+    cart_id          UUID NOT NULL REFERENCES carts (cart_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (cart_id, product_id)
+);
+
+CREATE INDEX idx_carts_customer ON carts (customer_id);
+CREATE INDEX idx_carts_status   ON carts (status);

package/templates/default/domains/Shopping/systems/cart-system/index.mdx

@@ -0,0 +1,53 @@
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+summary: |
+  Internal system that owns the customer's shopping cart and the checkout flow. It is the source of truth for cart contents and publishes an event when a cart is checked out.
+owners:
+  - shopping-platform
+services:
+  - id: cart-api
+containers:
+  - id: cart-database
+relationships:
+  - id: promotion-system
+    label: calculates discounts via
+actors:
+  - id: shopper
+    name: Shopper
+    label: adds items and checks out
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Cart System** owns the shopping cart at Acme Inc. It accepts commands to add and remove items and to check out, persists cart contents in the [[container|cart-database]], and asks the [[system|promotion-system]] to calculate the discounts that apply. When a cart is checked out it publishes a [[event|cart-checked-out]] event.
+
+## 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\|cart-api]]        | Service    | Public-facing API. Handles add/remove/checkout commands and publishes the checkout event. |
+| [[container\|cart-database]] | Data store | PostgreSQL system of record for shopping carts and their items.                           |
+
+## Messages this system publishes
+
+- [[event|cart-checked-out]] — a customer has checked out their cart.

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx

@@ -0,0 +1,32 @@
+---
+id: add-item-to-cart
+name: Add Item To Cart
+version: 1.0.0
+summary: |
+  Command to add an item to a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/items
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AddItemToCart` is handled by the [[service|cart-api]]. It adds an item (or increases its quantity) in the cart and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AddItemToCart",
+  "description": "Command to add an item to a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to add",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to add",
+      "type": "integer",
+      "minimum": 1,
+      "default": 1
+    }
+  },
+  "required": ["cartId", "productId", "quantity"]
+}

package/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx

@@ -0,0 +1,32 @@
+---
+id: checkout-cart
+name: Checkout Cart
+version: 1.0.0
+summary: |
+  Command to check out a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/checkout
+  statusCodes: ['200', '400', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CheckoutCart` is handled by the [[service|cart-api]]. It finalises the cart — pricing it (including discounts from the [[system|promotion-system]]) — and on success publishes a [[event|cart-checked-out]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />