@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

@@ -0,0 +1,41 @@
+---
+dictionary:
+  - id: Payment
+    name: Payment
+    summary: 'A charge taken from a customer to pay for an order.'
+    description: |
+      A payment is the central concept of the Payments domain. It is owned by the Payment Processing
+      System, which records every payment's status (REQUESTED, SUCCEEDED or FAILED). The actual money
+      movement happens at the external payment processor.
+    icon: CreditCard
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method, confirming funds are available before capture."
+    icon: ShieldCheck
+  - id: Capture
+    name: Capture
+    summary: 'Taking the held funds from an authorized payment — turning an authorization into an actual charge.'
+    icon: Banknote
+  - id: Refund
+    name: Refund
+    summary: 'Returning money to a customer for a previous payment, in full or in part.'
+    icon: Undo2
+  - id: Payment Processor
+    name: Payment Processor
+    summary: "The external provider (Stripe) that charges cards and issues refunds on Acme Inc's behalf."
+    description: |
+      The payment processor is a third party. Acme Inc never stores raw card details — it delegates
+      the actual charge and refund to the processor and reacts to the outcomes it reports back.
+    icon: Building2
+  - id: Fraud Screening
+    name: Fraud Screening
+    summary: 'Checking a payment for signs of fraud before allowing the charge to proceed.'
+    description: |
+      Fraud screening is performed by an external Fraud Detection provider. It returns a verdict —
+      passed or failed — that determines whether a payment is allowed or blocked.
+    icon: ShieldAlert
+  - id: Webhook
+    name: Webhook
+    summary: 'A callback the payment processor sends to report the outcome of a charge or refund.'
+    icon: Webhook
+---

package/templates/default/domains/Reviews/asyncapi.yml

@@ -0,0 +1,181 @@
+asyncapi: 3.0.0
+
+info:
+  title: Review Moderation Worker
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Review Moderation Worker.
+
+    The worker consumes submitted and flagged reviews, screens them for spam, abuse
+    and policy violations, and publishes the outcome (published or rejected).
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  reviewIntake:
+    address: reviews.intake
+    title: Reviews to moderate
+    description: Reviews that need screening — newly submitted or flagged for re-moderation.
+    messages:
+      ReviewSubmitted:
+        $ref: '#/components/messages/ReviewSubmitted'
+      ReviewFlagged:
+        $ref: '#/components/messages/ReviewFlagged'
+
+  reviewOutcomes:
+    address: reviews.outcomes
+    title: Moderation outcomes
+    description: The decisions the worker publishes after screening a review.
+    messages:
+      ReviewPublished:
+        $ref: '#/components/messages/ReviewPublished'
+      ReviewRejected:
+        $ref: '#/components/messages/ReviewRejected'
+
+operations:
+  receiveReviewSubmitted:
+    action: receive
+    title: Review Submitted
+    summary: Screen a newly submitted review.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewSubmitted'
+
+  receiveReviewFlagged:
+    action: receive
+    title: Review Flagged
+    summary: Re-screen a previously published review that has been flagged.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewFlagged'
+
+  publishReviewPublished:
+    action: send
+    title: Review Published
+    summary: Published when a review passes moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewPublished'
+
+  publishReviewRejected:
+    action: send
+    title: Review Rejected
+    summary: Published when a review fails moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewRejected'
+
+components:
+  messages:
+    ReviewSubmitted:
+      name: ReviewSubmitted
+      title: Review Submitted
+      summary: A customer submitted a review; it awaits moderation.
+      payload:
+        $ref: '#/components/schemas/ReviewSubmitted'
+    ReviewFlagged:
+      name: ReviewFlagged
+      title: Review Flagged
+      summary: A published review was flagged and needs re-screening.
+      payload:
+        $ref: '#/components/schemas/ReviewFlagged'
+    ReviewPublished:
+      name: ReviewPublished
+      title: Review Published
+      summary: A review passed moderation and is visible on the storefront.
+      payload:
+        $ref: '#/components/schemas/ReviewPublished'
+    ReviewRejected:
+      name: ReviewRejected
+      title: Review Rejected
+      summary: A review failed moderation and will not be shown.
+      payload:
+        $ref: '#/components/schemas/ReviewRejected'
+
+  schemas:
+    ReviewSubmitted:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+        submittedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, customerId, rating, submittedAt]
+    ReviewFlagged:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        flagCount:
+          type: integer
+          minimum: 1
+        flaggedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, reason, flaggedAt]
+    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]
+    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/containers/rating-cache/index.mdx

@@ -0,0 +1,29 @@
+---
+id: rating-cache
+name: Rating Cache
+version: 1.0.0
+summary: Redis cache that serves each product's aggregate star rating with low latency.
+container_type: cache
+technology: redis@7
+authoritative: false
+access_mode: readWrite
+purpose: Fast read store for aggregate product ratings
+classification: internal
+retention: transient
+residency: eu-west-1
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Rating Cache** holds the aggregate rating (average score and review count) for each product. It is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying published reviews.
+
+### What does it store?
+
+- **Aggregate rating** — one entry per product: average rating, review count and last-updated timestamp.
+
+### Access patterns
+
+- The [[service|rating-aggregator]] writes the aggregate rating whenever a review is published.
+- The [[service|review-api]] reads it to serve [[query|get-product-reviews]].

package/templates/default/domains/Reviews/containers/review-database/index.mdx

@@ -0,0 +1,33 @@
+---
+id: review-database
+name: Review Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for reviews and their moderation state.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for reviews, ratings and moderation decisions
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Review Database** is the authoritative store for every review in the Reviews & Ratings domain. The [[service|review-api]] writes new reviews to it, and the [[service|review-moderation-worker]] records each moderation decision against the stored review.
+
+### What does it store?
+
+- **Reviews** — one row per review: product, customer, rating, title, body and lifecycle status (`submitted`, `published`, `rejected`).
+- **Moderation decisions** — the outcome and reason for each moderated review, kept for audit.
+
+### Access patterns
+
+- The [[service|review-api]] writes new reviews and reads published reviews.
+- The [[service|review-moderation-worker]] reads submitted reviews and writes moderation outcomes.
+- The [[service|rating-aggregator]] reads published reviews to recompute aggregates.

package/templates/default/domains/Reviews/entities/moderation-decision/index.mdx

@@ -0,0 +1,38 @@
+---
+id: moderation-decision
+name: Moderation Decision
+version: 1.0.0
+identifier: moderationDecisionId
+summary: The outcome of reviewing submitted customer feedback.
+owners:
+  - reviews-platform
+properties:
+  - name: moderationDecisionId
+    type: UUID
+    required: true
+    description: Unique moderation decision identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being moderated.
+    references: review
+    relationType: decides
+    referencesIdentifier: reviewId
+  - name: outcome
+    type: string
+    required: true
+    description: Moderation result.
+    enum:
+      - published
+      - rejected
+  - name: decidedAt
+    type: datetime
+    required: true
+    description: Time the decision was made.
+---
+
+## Overview
+
+Moderation Decision records why a review became published or rejected and supports audit of [[service|review-moderation-worker]] behavior.
+
+<EntityPropertiesTable />

package/templates/default/domains/Reviews/entities/rating-summary/index.mdx

@@ -0,0 +1,35 @@
+---
+id: rating-summary
+name: Rating Summary
+version: 1.0.0
+identifier: productId
+summary: Aggregated review statistics for a product.
+owners:
+  - reviews-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being summarized.
+    references: product
+    relationType: summarizes
+    referencesIdentifier: productId
+  - name: averageRating
+    type: decimal
+    required: true
+    description: Average published rating.
+  - name: reviewCount
+    type: integer
+    required: true
+    description: Number of published reviews.
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the summary was recalculated.
+---
+
+## Overview
+
+Rating Summary is the read model maintained by [[service|rating-aggregator]] and stored in [[container|rating-cache]].
+
+<EntityPropertiesTable />

package/templates/default/domains/Reviews/entities/review/index.mdx

@@ -0,0 +1,63 @@
+---
+id: review
+name: Review
+version: 1.0.0
+identifier: reviewId
+aggregateRoot: true
+summary: A customer's review and rating of a product, including its moderation lifecycle.
+owners:
+  - reviews-platform
+properties:
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Unique identifier for the review.
+  - name: productId
+    type: string
+    required: true
+    description: The product being reviewed.
+    references: product
+    relationType: reviews
+    referencesIdentifier: productId
+  - name: customerId
+    type: string
+    required: true
+    description: The customer who wrote the review.
+    references: customer-profile
+    relationType: writtenBy
+    referencesIdentifier: customerId
+  - name: rating
+    type: integer
+    required: true
+    description: Star rating from 1 to 5.
+  - name: title
+    type: string
+    required: false
+    description: Short headline for the review.
+  - name: body
+    type: string
+    required: true
+    description: The review text.
+  - name: status
+    type: string
+    required: true
+    description: Lifecycle status of the review.
+    enum:
+      - submitted
+      - published
+      - rejected
+  - name: submittedAt
+    type: datetime
+    required: true
+    description: When the review was submitted.
+---
+
+## Overview
+
+The **Review** is the core aggregate of the Reviews & Ratings domain. It captures a customer's rating and written feedback for a product, along with the moderation `status` that controls whether it is visible on the storefront.
+
+A review moves through three states:
+
+1. **submitted** — stored by the [[service|review-api]], awaiting moderation.
+2. **published** — passed moderation and visible (the [[service|rating-aggregator]] folds it into the product's rating).
+3. **rejected** — failed moderation and never shown, but kept for audit.

package/templates/default/domains/Reviews/entities/review-flag/index.mdx

@@ -0,0 +1,35 @@
+---
+id: review-flag
+name: Review Flag
+version: 1.0.0
+identifier: flagId
+summary: A customer report that a review may violate policy.
+owners:
+  - reviews-platform
+properties:
+  - name: flagId
+    type: UUID
+    required: true
+    description: Unique review flag identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being reported.
+    references: review
+    relationType: flags
+    referencesIdentifier: reviewId
+  - name: reason
+    type: string
+    required: true
+    description: Reason selected by the customer.
+  - name: flaggedAt
+    type: datetime
+    required: true
+    description: Time the review was flagged.
+---
+
+## Overview
+
+Review Flag captures [[command|flag-review]] interactions and can send a published review back through moderation.
+
+<EntityPropertiesTable />

package/templates/default/domains/Reviews/entities/review-vote/index.mdx

@@ -0,0 +1,38 @@
+---
+id: review-vote
+name: Review Vote
+version: 1.0.0
+identifier: voteId
+summary: A customer's helpfulness vote on a product review.
+owners:
+  - reviews-platform
+properties:
+  - name: voteId
+    type: UUID
+    required: true
+    description: Unique review vote identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being voted on.
+    references: review
+    relationType: votesOn
+    referencesIdentifier: reviewId
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who voted.
+    references: customer-profile
+    relationType: submittedBy
+    referencesIdentifier: customerId
+  - name: votedAt
+    type: datetime
+    required: true
+    description: Time the vote was submitted.
+---
+
+## Overview
+
+Review Vote captures [[command|vote-review-helpful]] interactions and contributes to review helpfulness ranking.
+
+<EntityPropertiesTable />

package/templates/default/domains/Reviews/flows/review-submission/index.mdx

@@ -0,0 +1,120 @@
+---
+id: review-submission
+name: Review Submission
+version: 1.0.0
+summary: |
+  How a customer's product review travels from submission, through moderation, to being published and folded into the product's aggregate rating.
+owners:
+  - reviews-platform
+steps:
+  - id: customer_submits
+    title: Customer submits a review
+    actor:
+      name: Customer
+      summary: A customer writes a review and rating for a product they purchased.
+    next_step:
+      id: review_api
+      label: Submit review
+
+  - id: review_api
+    title: Review API
+    service:
+      id: review-api
+      version: 1.0.0
+    next_step:
+      id: review_database
+      label: Store review
+
+  - id: review_database
+    title: Review Database
+    container:
+      id: review-database
+    next_step:
+      id: review_submitted
+      label: Review stored
+
+  - id: review_submitted
+    title: Review Submitted
+    message:
+      id: review-submitted
+      version: 1.0.0
+    next_step:
+      id: moderation_worker
+      label: Screen review
+
+  - id: moderation_worker
+    title: Review Moderation Worker
+    service:
+      id: review-moderation-worker
+      version: 1.0.0
+    next_steps:
+      - id: review_published
+        label: Approved
+      - id: review_rejected
+        label: Rejected
+
+  - id: review_published
+    title: Review Published
+    message:
+      id: review-published
+      version: 1.0.0
+    next_step:
+      id: rating_aggregator
+      label: Update rating
+
+  - id: review_rejected
+    title: Review Rejected
+    message:
+      id: review-rejected
+      version: 1.0.0
+    next_step:
+      id: rejected_outcome
+      label: Not shown
+
+  - id: rating_aggregator
+    title: Rating Aggregator
+    service:
+      id: rating-aggregator
+      version: 1.0.0
+    next_step:
+      id: rating_cache
+      label: Write aggregate
+
+  - id: rating_cache
+    title: Rating Cache
+    container:
+      id: rating-cache
+    next_step:
+      id: published_outcome
+      label: Visible on storefront
+
+  - id: published_outcome
+    title: Review is live
+    custom:
+      title: Review is live
+      color: green
+      icon: StarIcon
+      type: Outcome
+      summary: The review is published and the product's aggregate rating is updated and served from the cache.
+
+  - id: rejected_outcome
+    title: Review rejected
+    custom:
+      title: Review rejected
+      color: red
+      icon: NoSymbolIcon
+      type: Outcome
+      summary: The review failed moderation. It is kept for audit but never shown on the storefront.
+---
+
+## Overview
+
+**Review Submission** documents the journey of a customer review from submission through moderation to publication. A review is only ever folded into a product's rating once it has been approved.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service|review-api]], which stores it in the [[container|review-database]] and publishes [[event|review-submitted]].
+2. The [[service|review-moderation-worker]] screens the review and publishes either [[event|review-published]] or [[event|review-rejected]].
+3. On approval, the [[service|rating-aggregator]] updates the product's aggregate rating in the [[container|rating-cache]] and the review goes live.