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

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

@@ -0,0 +1,69 @@
+---
+id: payments
+name: Payments
+version: 1.0.0
+summary: |
+  The Payments domain takes payment for orders and processes refunds. It orchestrates authorization and capture through an external payment processor, and screens payments for fraud.
+owners:
+  - payments-platform
+systems:
+  - id: payment-processing-system
+    version: 1.0.0
+  - id: stripe
+    version: 1.0.0
+  - id: fraud-detection
+    version: 1.0.0
+entities:
+  - id: payment
+    version: 1.0.0
+  - id: payment-authorization
+    version: 1.0.0
+  - id: refund
+    version: 1.0.0
+  - id: fraud-check
+    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 **Payments** domain is responsible for moving money. It authorizes and captures payment for orders, issues refunds, and screens payments for fraud. It owns one internal system and integrates with two external providers:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/payment-processing-system/1.0.0"
+    title="Payment Processing System"
+    description="Orchestrates authorization, capture and refunds for orders."
+  />
+  <Tile
+    icon="BuildingLibraryIcon"
+    href="/docs/systems/stripe/1.0.0"
+    title="Stripe"
+    description="External payment processor that charges cards and issues refunds."
+  />
+  <Tile
+    icon="ShieldExclamationIcon"
+    href="/docs/systems/fraud-detection/1.0.0"
+    title="Fraud Detection"
+    description="External provider that screens payments for fraud."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Payment Processing System** is the internal orchestrator. When the Ordering domain authorizes a payment, it requests payment via the external **Stripe** system and, in parallel, asks **Fraud Detection** to screen the payment. Stripe reports back whether the payment succeeded or failed, and the Payment Processing System records the outcome.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />

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

@@ -0,0 +1,49 @@
+---
+id: fraud-detection
+name: Fraud Detection
+version: 1.0.0
+scope: external
+summary: |
+  External provider that screens payments for fraud. It consumes payment requests and returns a pass or fail verdict.
+owners:
+  - payments-platform
+services:
+  - id: fraud-api
+relationships:
+  - id: payment-processing-system
+    label: screens payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+**Fraud Detection** is an external provider Acme Inc uses to screen payments for fraud. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+It consumes [[event|payment-requested]] and returns a verdict via [[event|fraud-check-passed]] or [[event|fraud-check-failed]].
+
+## 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\|fraud-api]] | Service | Screens a payment for fraud and returns a pass/fail verdict. |
+
+## Messages this system publishes
+
+- [[event\|fraud-check-passed]] — a payment passed fraud screening.
+- [[event\|fraud-check-failed]] — a payment failed fraud screening.

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

@@ -0,0 +1,29 @@
+---
+id: fraud-check-failed
+name: Fraud Check Failed
+version: 1.0.0
+summary: |
+  Published when a payment fails fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckFailed` is published by the [[service|fraud-api]] when a payment is flagged as fraudulent. The [[system|payment-processing-system]] uses it to block the charge and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckFailed",
+  "description": "Published when a payment fails fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; higher is riskier"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["HIGH_RISK_SCORE", "BLOCKLISTED", "VELOCITY", "MISMATCH"]
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "checkedAt"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: fraud-check-passed
+name: Fraud Check Passed
+version: 1.0.0
+summary: |
+  Published when a payment passes fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckPassed` is published by the [[service|fraud-api]] when a payment clears fraud screening. The [[system|payment-processing-system]] uses it to allow the charge to proceed.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckPassed",
+  "description": "Published when a payment passes fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; lower is safer"
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "checkedAt"]
+}

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.