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

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.

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

@@ -0,0 +1,93 @@
+---
+id: reviews
+name: Reviews & Ratings
+version: 1.0.0
+summary: |
+  The Reviews & Ratings domain owns customer feedback on products — how reviews are submitted, moderated, published and aggregated into the star ratings shown across the storefront.
+owners:
+  - reviews-platform
+services:
+  - id: review-api
+    version: 1.0.0
+  - id: review-moderation-worker
+    version: 1.0.0
+  - id: rating-aggregator
+    version: 1.0.0
+entities:
+  - id: review
+    version: 1.0.0
+  - id: moderation-decision
+    version: 1.0.0
+  - id: rating-summary
+    version: 1.0.0
+  - id: review-vote
+    version: 1.0.0
+  - id: review-flag
+    version: 1.0.0
+flows:
+  - id: review-submission
+    version: 1.0.0
+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-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+  - id: rating-updated
+    version: 1.0.0
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Review API
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Reviews Eventing
+badges:
+  - content: Supporting domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+---
+
+## Overview
+
+The **Reviews & Ratings** domain is responsible for everything to do with customer feedback on products: accepting reviews, moderating them for quality and abuse, publishing the approved ones, and aggregating them into the star ratings shown across the storefront.
+
+Unlike most other domains in the catalog, Reviews & Ratings is modelled **without systems** — its services, data stores and flows hang directly off the domain.
+
+### What's inside
+
+| Component                             | Type       | Responsibility                                                          |
+| ------------------------------------- | ---------- | ----------------------------------------------------------------------- |
+| [[service\|review-api]]               | Service    | Accepts review submissions and serves product reviews.                  |
+| [[service\|review-moderation-worker]] | Service    | Screens submitted reviews and publishes or rejects them.                |
+| [[service\|rating-aggregator]]        | Service    | Keeps each product's aggregate rating in sync as reviews are published. |
+| [[container\|review-database]]        | Data Store | System of record for reviews and their moderation state.                |
+| [[container\|rating-cache]]           | Data Store | Fast read store for aggregate product ratings.                          |
+| [[entity\|review]]                    | Entity     | The core review aggregate.                                              |
+
+The diagram below shows the services, data stores and messages that make up this domain.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service\|review-api]], which stores it 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. The [[service\|rating-aggregator]] consumes [[event\|review-published]] and updates the product's aggregate rating, publishing [[event\|rating-updated]].
+
+Once a review is live, customers can interact with it: [[command\|vote-review-helpful]] updates its helpful count (publishing [[event\|review-helpful-voted]]), and [[command\|flag-review]] reports it for re-moderation (publishing [[event\|review-flagged]], which the [[service\|review-moderation-worker]] re-screens).

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

@@ -0,0 +1,209 @@
+openapi: 3.0.3
+info:
+  title: Review API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Reviews & Ratings domain. It is the entry point for
+    submitting reviews, flagging reviews, voting reviews helpful, and reading the
+    published reviews and aggregate rating for a product.
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Reviews
+    description: Submit, read and interact with product reviews.
+paths:
+  /products/{productId}/reviews:
+    get:
+      operationId: getProductReviews
+      summary: Get product reviews
+      description: Returns the published reviews and aggregate rating for a product.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum: [newest, highest, lowest, most_helpful]
+            default: newest
+      responses:
+        '200':
+          description: The published reviews and aggregate rating for the product.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductReviews'
+    post:
+      operationId: submitReview
+      summary: Submit a review
+      description: Submits a review for a product. On success a `ReviewSubmitted` event is published and the review awaits moderation.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubmitReviewRequest'
+      responses:
+        '202':
+          description: The review was accepted and is awaiting moderation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Review'
+        '400':
+          description: The request was invalid.
+  /reviews/{reviewId}/flags:
+    post:
+      operationId: flagReview
+      summary: Flag a review
+      description: Flags a published review for re-moderation. On success a `ReviewFlagged` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlagReviewRequest'
+      responses:
+        '202':
+          description: The flag was recorded.
+  /reviews/{reviewId}/helpful:
+    post:
+      operationId: voteReviewHelpful
+      summary: Vote a review helpful
+      description: Marks a review as helpful (or removes the vote). On success a `ReviewHelpfulVoted` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VoteReviewHelpfulRequest'
+      responses:
+        '200':
+          description: The helpful count was updated.
+components:
+  schemas:
+    Review:
+      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
+        status:
+          type: string
+          enum: [submitted, published, rejected]
+        helpfulCount:
+          type: integer
+          minimum: 0
+        submittedAt:
+          type: string
+          format: date-time
+    ProductReviews:
+      type: object
+      properties:
+        productId:
+          type: string
+        averageRating:
+          type: number
+          minimum: 0
+          maximum: 5
+        reviewCount:
+          type: integer
+          minimum: 0
+        reviews:
+          type: array
+          items:
+            $ref: '#/components/schemas/Review'
+    SubmitReviewRequest:
+      type: object
+      required: [customerId, rating, body]
+      properties:
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+    FlagReviewRequest:
+      type: object
+      required: [flaggedBy, reason]
+      properties:
+        flaggedBy:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        notes:
+          type: string
+    VoteReviewHelpfulRequest:
+      type: object
+      required: [customerId, vote]
+      properties:
+        customerId:
+          type: string
+        vote:
+          type: string
+          enum: [helpful, remove]

package/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: rating-updated
+name: Rating Updated
+version: 1.0.0
+summary: |
+  Published when a product's aggregate rating changes as a result of a newly published review.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RatingUpdated` is published by the [[service|rating-aggregator]] whenever a product's aggregate rating changes. Other domains (such as the storefront and search) can consume it to keep displayed ratings fresh.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RatingUpdated",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string" },
+    "averageRating": { "type": "number", "minimum": 0, "maximum": 5 },
+    "reviewCount": { "type": "integer", "minimum": 0 },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["productId", "averageRating", "reviewCount", "updatedAt"]
+}

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

@@ -0,0 +1,47 @@
+---
+id: rating-aggregator
+version: 1.0.0
+name: Rating Aggregator
+summary: |
+  Keeps each product's aggregate star rating up to date as reviews are published, and serves it fast from a cache.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-published
+    version: 1.0.0
+sends:
+  - id: rating-updated
+    version: 1.0.0
+writesTo:
+  - id: rating-cache
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: Go
+  url: 'https://github.com/acme/rating-aggregator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Rating Aggregator** consumes [[event|review-published]] and recomputes the affected product's aggregate rating (average score and review count). It writes the result to the [[container|rating-cache]] for fast reads and publishes [[event|rating-updated]] so other domains can stay in sync.
+
+### Responsibilities
+
+| Area        | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| Aggregation | Recomputes average rating and review count per product.      |
+| Caching     | Writes aggregate ratings to the [[container\|rating-cache]]. |
+| Eventing    | Publishes [[event\|rating-updated]] on every change.         |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx

@@ -0,0 +1,29 @@
+---
+id: flag-review
+name: Flag Review
+version: 1.0.0
+summary: |
+  Command issued by a customer or moderator to flag a published review for re-moderation.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FlagReview` is sent to the [[service|review-api]] when someone reports a published review as inappropriate. The API records the flag and publishes [[event|review-flagged]] so the review can be screened again.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FlagReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "flaggedBy": { "type": "string", "description": "Customer or moderator id raising the flag." },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "inappropriate", "other"] },
+    "notes": { "type": "string", "maxLength": 1000 },
+    "flaggedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "flaggedBy", "reason", "flaggedAt"]
+}

package/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx

@@ -0,0 +1,29 @@
+---
+id: submit-review
+name: Submit Review
+version: 1.0.0
+summary: |
+  Command issued by a customer to submit a review and rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SubmitReview` is sent to the [[service|review-api]] when a customer submits a review for a product they have purchased. The API validates and stores the review, then publishes [[event|review-submitted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SubmitReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid", "description": "Client-generated id for the review." },
+    "productId": { "type": "string", "description": "The product being reviewed." },
+    "customerId": { "type": "string", "description": "The customer submitting the review." },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Star rating from 1 to 5." },
+    "title": { "type": "string", "maxLength": 120 },
+    "body": { "type": "string", "maxLength": 5000 },
+    "submittedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "customerId", "rating", "body", "submittedAt"]
+}

package/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx

@@ -0,0 +1,29 @@
+---
+id: vote-review-helpful
+name: Vote Review Helpful
+version: 1.0.0
+summary: |
+  Command issued by a customer to mark a published review as helpful (or remove their vote).
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`VoteReviewHelpful` is sent to the [[service|review-api]] when a customer marks a review as helpful. The API updates the helpful count and publishes [[event|review-helpful-voted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "VoteReviewHelpful",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string" },
+    "vote": { "type": "string", "enum": ["helpful", "remove"], "description": "Add a helpful vote or remove an existing one." },
+    "votedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "customerId", "vote", "votedAt"]
+}