@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx

@@ -0,0 +1,51 @@
+---
+id: fraud-api
+version: 1.0.0
+name: Fraud API
+summary: |
+  External fraud screening API. It consumes payment requests and returns a pass or fail verdict for each.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+sends:
+  - id: fraud-check-passed
+    version: 1.0.0
+  - id: fraud-check-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/fraud-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Fraud API** screens payments for fraud. It consumes [[event|payment-requested]] from the [[system|payment-processing-system]] and returns a verdict — [[event|fraud-check-passed]] or [[event|fraud-check-failed]] — which the Payments domain uses to allow or block the charge.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Fraud verdicts"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Payment requests to screen"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx

@@ -0,0 +1,39 @@
+---
+id: payment-database
+name: Payment Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for payments and refunds.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for payments and refunds
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Payment Database** is the authoritative store for payments and refunds at Acme Inc. The [[service|payment-api]] and [[service|payment-worker]] read from and write to it as payments are authorized, charged and refunded.
+
+### What does it store?
+
+- **Payments** — one row per payment: id, order, amount, status and timestamps.
+- **Refunds** — one row per refund: id, payment, amount, status and timestamps.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Payment Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Payments and refunds are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.

package/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql

@@ -0,0 +1,25 @@
+-- Payment Database — system of record for payments and refunds
+
+CREATE TABLE payments (
+    payment_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id     UUID NOT NULL,
+    customer_id  UUID,
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'SUCCEEDED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE refunds (
+    refund_id    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    payment_id   UUID NOT NULL REFERENCES payments (payment_id),
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'PROCESSED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_payments_order  ON payments (order_id);
+CREATE INDEX idx_payments_status ON payments (status);

package/templates/default/domains/Payments/systems/payment-processing-system/index.mdx

@@ -0,0 +1,53 @@
+---
+id: payment-processing-system
+name: Payment Processing System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates payment for orders. It authorizes payments, requests charges from the external payment processor, handles the outcome, and issues refunds.
+owners:
+  - payments-platform
+services:
+  - id: payment-api
+  - id: payment-worker
+containers:
+  - id: payment-database
+relationships:
+  - id: stripe
+    label: requests charges from
+  - id: fraud-detection
+    label: screens payments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Payment Processing System** is the internal heart of the Payments domain. When the Ordering domain sends [[command|authorize-payment]], the [[service|payment-api]] records the intent in the [[container|payment-database]] and the [[service|payment-worker]] requests a charge from the external [[system|stripe]] via [[event|payment-requested]]. Stripe reports the outcome back as [[event|payment-succeeded]] or [[event|payment-failed]], which the worker records. The system also issues refunds via [[event|refund-requested]].
+
+## 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\|payment-api]]        | Service    | Receives authorization requests and records payment intent.     |
+| [[service\|payment-worker]]     | Service    | Drives charges and refunds against Stripe and records outcomes. |
+| [[container\|payment-database]] | Data store | PostgreSQL system of record for payments and refunds.           |
+
+## Messages this system publishes
+
+- [[event\|payment-requested]] — a charge has been requested from the payment processor.
+- [[event\|refund-requested]] — a refund has been requested from the payment processor.

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx

@@ -0,0 +1,51 @@
+---
+id: payment-api
+version: 1.0.0
+name: Payment API
+summary: |
+  Receives payment authorization requests from the Ordering domain and records the payment intent, kicking off the charge against the payment processor.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: authorize-payment
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/payment-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment API** is the entry point to the Payment Processing System. It receives [[command|authorize-payment]] from the Ordering domain, records the payment intent in the [[container|payment-database]], and leaves the [[service|payment-worker]] to drive the charge against [[system|stripe]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="The authorize-payment command from Ordering"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area          | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| Authorization | Receives and validates [[command\|authorize-payment]].         |
+| Persistence   | Records payment intent in the [[container\|payment-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx

@@ -0,0 +1,29 @@
+---
+id: payment-requested
+name: Payment Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a charge from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to charge a customer for an order. Stripe responds with [[event|payment-succeeded]] or [[event|payment-failed]]. The [[system|fraud-detection]] system also consumes this event to screen the payment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentRequested",
+  "description": "Published when a charge is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to charge, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "requestedAt"]
+}

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx

@@ -0,0 +1,29 @@
+---
+id: refund-requested
+name: Refund Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a refund from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to refund a previous charge — for example when an order is cancelled after payment. Stripe responds with [[event|refund-processed]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundRequested",
+  "description": "Published when a refund is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to refund, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "reason": { "type": "string" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "requestedAt"]
+}

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx

@@ -0,0 +1,66 @@
+---
+id: payment-worker
+version: 1.0.0
+name: Payment Worker
+summary: |
+  Drives charges and refunds against the external payment processor and records the outcomes. It requests payments and refunds, and consumes the success/failure events Stripe returns.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+sends:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/payment-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment Worker** drives money movement. It requests charges from the external [[system|stripe]] via [[event|payment-requested]] and refunds via [[event|refund-requested]], then consumes the [[event|payment-succeeded]] and [[event|payment-failed]] events Stripe returns and records the outcome in the [[container|payment-database]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Payment and refund requests"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Payment outcomes from Stripe"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area        | Description                                                                         |
+| ----------- | ----------------------------------------------------------------------------------- |
+| Charging    | Requests charges via [[event\|payment-requested]].                                  |
+| Refunds     | Requests refunds via [[event\|refund-requested]].                                   |
+| Outcomes    | Consumes [[event\|payment-succeeded]] / [[event\|payment-failed]] and records them. |
+| Persistence | Reads from and writes to the [[container\|payment-database]].                       |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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

@@ -0,0 +1,52 @@
+---
+id: stripe
+name: Stripe
+version: 1.0.0
+scope: external
+summary: |
+  External payment processor used by Acme Inc to charge cards and issue refunds. It receives payment and refund requests and reports outcomes back via webhook events.
+owners:
+  - payments-platform
+services:
+  - id: stripe-payments-api
+  - id: stripe-webhook-endpoint
+relationships:
+  - id: payment-processing-system
+    label: processes payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+[Stripe](https://stripe.com) is the external payment processor Acme Inc uses to charge customer cards and issue refunds. It is owned and operated by Stripe — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+Stripe receives [[event|payment-requested]] and [[event|refund-requested]], and reports outcomes back via [[event|payment-succeeded]], [[event|payment-failed]] and [[event|refund-processed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                            | Type    | Responsibility                                                           |
+| ------------------------------------ | ------- | ------------------------------------------------------------------------ |
+| [[service\|stripe-payments-api]]     | Service | Accepts charge and refund requests and processes them.                   |
+| [[service\|stripe-webhook-endpoint]] | Service | Delivers payment and refund outcomes back to Acme Inc as webhook events. |
+
+## Messages this system publishes
+
+- [[event\|payment-succeeded]] — a charge succeeded.
+- [[event\|payment-failed]] — a charge failed.
+- [[event\|refund-processed]] — a refund was processed.

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