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

package/templates/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx

@@ -0,0 +1,42 @@
+---
+id: stripe-payments-api
+version: 1.0.0
+name: Payments API
+summary: |
+  Stripe's API for charging cards and issuing refunds. Acme Inc's Payment Processing System calls it to request payments and refunds.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payments API** is Stripe's external interface for charging cards and issuing refunds. The [[system|payment-processing-system]] sends [[event|payment-requested]] and [[event|refund-requested]], and Stripe processes them and reports the outcome back through its [[service|stripe-webhook-endpoint]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Payment and refund requests"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx

@@ -0,0 +1,29 @@
+---
+id: payment-failed
+name: Payment Failed
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge fails.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentFailed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge fails — for example a declined card. The [[service|payment-worker]] consumes it and records the payment as failed, which ultimately leads the order to be cancelled.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentFailed",
+  "description": "Published when a charge fails",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CARD_DECLINED", "INSUFFICIENT_FUNDS", "EXPIRED_CARD", "PROCESSING_ERROR"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "failedAt"]
+}

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx

@@ -0,0 +1,29 @@
+---
+id: payment-succeeded
+name: Payment Succeeded
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge succeeds.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentSucceeded` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge succeeds. The [[service|payment-worker]] consumes it and records the payment as succeeded.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentSucceeded",
+  "description": "Published when a charge succeeds",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount charged, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processorReference": { "type": "string", "description": "Stripe's charge identifier" },
+    "succeededAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "succeededAt"]
+}

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx

@@ -0,0 +1,29 @@
+---
+id: refund-processed
+name: Refund Processed
+version: 1.0.0
+summary: |
+  Published by Stripe when a refund has been processed.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundProcessed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested refund has been processed. The [[service|payment-worker]] consumes it and records the refund as complete.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundProcessed",
+  "description": "Published when a refund has been processed",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount refunded, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "processedAt"]
+}

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx

@@ -0,0 +1,44 @@
+---
+id: stripe-webhook-endpoint
+version: 1.0.0
+name: Webhook Endpoint
+summary: |
+  Stripe's webhook delivery for payment and refund outcomes. It notifies Acme Inc whether a charge succeeded or failed, and when a refund is processed.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+sends:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+  - id: refund-processed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Webhook Endpoint** is how Stripe reports outcomes back to Acme Inc. After processing a request from the [[service|stripe-payments-api]], it delivers [[event|payment-succeeded]], [[event|payment-failed]] or [[event|refund-processed]] to the [[system|payment-processing-system]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Payment and refund outcomes"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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