@eventcatalog/create-eventcatalog 3.0.9 → 3.0.11

package/templates/default/domains/Payment/entities/Address/index.mdx

@@ -0,0 +1,162 @@
+---
+id: Address
+name: Address
+version: 1.0.0
+identifier: addressId
+summary: Represents shipping and billing addresses for customers and orders.
+properties:
+  - name: addressId
+    type: UUID
+    required: true
+    description: Unique identifier for the address
+  - name: customerId
+    type: UUID
+    required: false
+    description: Customer this address belongs to
+    references: Customer
+    referencesIdentifier: customerId
+    relationType: hasOne
+  - name: type
+    type: string
+    required: true
+    description: Type of address
+    enum: ['billing', 'shipping', 'both']
+  - name: firstName
+    type: string
+    required: true
+    description: First name of the recipient
+  - name: lastName
+    type: string
+    required: true
+    description: Last name of the recipient
+  - name: company
+    type: string
+    required: false
+    description: Company name if applicable
+  - name: addressLine1
+    type: string
+    required: true
+    description: Primary address line (street address)
+  - name: addressLine2
+    type: string
+    required: false
+    description: Secondary address line (apartment, suite, etc.)
+  - name: city
+    type: string
+    required: true
+    description: City name
+  - name: state
+    type: string
+    required: true
+    description: State or province
+  - name: postalCode
+    type: string
+    required: true
+    description: Postal or ZIP code
+  - name: country
+    type: string
+    required: true
+    description: Country code (ISO 3166-1 alpha-2)
+  - name: phone
+    type: string
+    required: false
+    description: Phone number for delivery contact
+  - name: isDefault
+    type: boolean
+    required: true
+    description: Whether this is the default address for the customer
+  - name: isValidated
+    type: boolean
+    required: true
+    description: Whether the address has been validated
+  - name: validationDetails
+    type: object
+    required: false
+    description: Address validation details
+    properties:
+      - name: validatedAt
+        type: DateTime
+        description: When the address was validated
+      - name: validationService
+        type: string
+        description: Service used for validation
+      - name: confidence
+        type: decimal
+        description: Validation confidence score
+  - name: geocoordinates
+    type: object
+    required: false
+    description: Geographic coordinates for the address
+    properties:
+      - name: latitude
+        type: decimal
+        description: Latitude coordinate
+      - name: longitude
+        type: decimal
+        description: Longitude coordinate
+  - name: deliveryInstructions
+    type: string
+    required: false
+    description: Special delivery instructions
+  - name: orders
+    type: array
+    items:
+      type: Order
+    required: false
+    description: Orders using this address
+    references: Order
+    referencesIdentifier: shippingAddress
+    relationType: hasMany
+  - name: payments
+    type: array
+    items:
+      type: Payment
+    required: false
+    description: Payments using this as billing address
+    references: Payment
+    referencesIdentifier: billingAddress
+    relationType: hasMany
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the address was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the address was last updated
+---
+
+## Overview
+
+The Address entity stores shipping and billing addresses for customers, orders, and payments. It supports address validation, geocoding, and delivery instructions to ensure accurate order fulfillment.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Customer:** An address can belong to one `Customer` (identified by `customerId`).
+* **Order:** An address can be used by multiple `Order` entities for shipping.
+* **Payment:** An address can be used by multiple `Payment` entities for billing.
+
+## Address Types
+
+* **Billing:** Used for payment processing and invoicing
+* **Shipping:** Used for order delivery
+* **Both:** Can be used for both billing and shipping
+
+## Examples
+
+* **Address #1:** John Doe's home address - default shipping and billing address.
+* **Address #2:** Corporate office address - billing only, validated with high confidence.
+* **Address #3:** Gift recipient address - shipping only, with special delivery instructions.
+
+## Business Rules
+
+* Each customer can have only one default address per type
+* Addresses must be validated before being marked as default
+* International addresses require country-specific validation
+* Geocoordinates are automatically populated when available
+* Address changes should create new versions for audit trail
+* PO Box addresses may have shipping restrictions
+* Address validation improves delivery success rates

package/templates/default/domains/Payment/entities/Invoice/index.mdx

@@ -0,0 +1,89 @@
+---
+id: Invoice
+name: Invoice
+version: 1.0.0
+identifier: invoiceId
+summary: Represents a bill issued to a customer, detailing charges for products or services.
+
+properties:
+  - name: invoiceId
+    type: UUID
+    required: true
+    description: Unique identifier for the invoice.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Identifier of the customer being invoiced
+    references: Customer
+    relationType: hasOne
+  - name: orderId # Optional, if invoice is directly tied to a single order
+    type: UUID
+    required: false
+    description: Identifier of the associated order, if applicable.
+  - name: subscriptionId # Optional, if invoice is for a subscription period
+    type: UUID
+    required: false
+    description: Identifier of the associated subscription, if applicable.
+  - name: invoiceNumber
+    type: string
+    required: true
+    description: Human-readable, sequential identifier for the invoice (may have specific format).
+  - name: issueDate
+    type: Date
+    required: true
+    description: Date the invoice was generated and issued.
+  - name: dueDate
+    type: Date
+    required: true
+    description: Date by which the payment for the invoice is due.
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: The total amount due on the invoice.
+  - name: currency
+    type: string # ISO 4217 code
+    required: true
+    description: Currency of the invoice amount.
+  - name: status
+    type: string # (e.g., Draft, Sent, Paid, Overdue, Void)
+    required: true
+    description: Current status of the invoice.
+  - name: billingAddressId # Address used for this specific invoice
+    type: UUID
+    required: true
+    description: Identifier for the billing address used on this invoice.
+  - name: lineItems
+    type: array
+    items:
+      type: InvoiceLineItem # Assuming a value object or separate entity for line items
+    required: true
+    description: List of individual items or services being charged on the invoice.
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Timestamp when the invoice record was created.
+  - name: paidAt # Timestamp when payment was confirmed
+    type: DateTime
+    required: false
+    description: Timestamp when the invoice was marked as paid.
+---
+
+## Overview
+
+The Invoice entity represents a formal request for payment issued by the business to a customer. It details the products, services, quantities, prices, taxes, and total amount due, along with payment terms.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Customer:** An invoice is issued to one `Customer`.
+*   **Order/Subscription:** An invoice may be related to one or more `Order`s or a specific `Subscription` period.
+*   **Payment:** An invoice is settled by one or more `Payment` transactions.
+*   **InvoiceLineItem:** An invoice contains multiple `InvoiceLineItem`s detailing the charges.
+*   **BillingProfile:** Invoice generation often uses details from the customer's `BillingProfile`.
+
+## Examples
+
+*   Invoice #INV-00123 issued to Jane Doe for her monthly subscription renewal, due in 15 days.
+*   Invoice #INV-00124 issued to Acme Corp for consulting services rendered in the previous month, status Paid. 

package/templates/default/domains/Payment/entities/Payment/index.mdx

@@ -0,0 +1,137 @@
+---
+id: Payment
+name: Payment
+version: 1.0.0
+identifier: paymentId
+aggregateRoot: true
+summary: Represents payment transactions for orders in the e-commerce system.
+properties:
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Unique identifier for the payment
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order this payment is associated with
+    references: Order
+    referencesIdentifier: orderId
+    relationType: hasOne
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who made the payment
+    references: Customer
+    referencesIdentifier: customerId
+    relationType: hasOne
+  - name: amount
+    type: decimal
+    required: true
+    description: Payment amount
+  - name: currency
+    type: string
+    required: true
+    description: Currency code (e.g., USD, EUR, GBP)
+  - name: paymentMethod
+    type: string
+    required: true
+    description: Payment method used
+    enum: ['credit_card', 'debit_card', 'paypal', 'stripe', 'bank_transfer', 'apple_pay', 'google_pay']
+  - name: paymentMethodDetails
+    type: object
+    required: false
+    description: Additional payment method specific details
+    properties:
+      - name: cardLast4
+        type: string
+        description: Last 4 digits of card number
+      - name: cardType
+        type: string
+        description: Card type (Visa, MasterCard, etc.)
+      - name: expiryMonth
+        type: integer
+        description: Card expiry month
+      - name: expiryYear
+        type: integer
+        description: Card expiry year
+  - name: status
+    type: string
+    required: true
+    description: Current payment status
+    enum: ['pending', 'processing', 'completed', 'failed', 'cancelled', 'refunded', 'partially_refunded']
+  - name: transactionId
+    type: string
+    required: false
+    description: External payment processor transaction ID
+  - name: gatewayResponse
+    type: object
+    required: false
+    description: Raw response from payment gateway
+  - name: billingAddress
+    type: Address
+    required: true
+    description: Billing address for the payment
+    references: Address
+    referencesIdentifier: addressId
+    relationType: hasOne
+  - name: processedAt
+    type: DateTime
+    required: false
+    description: Date and time when payment was processed
+  - name: failureReason
+    type: string
+    required: false
+    description: Reason for payment failure if applicable
+  - name: refunds
+    type: array
+    items:
+      type: PaymentRefund
+    required: false
+    description: Refunds associated with this payment
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the payment record was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the payment record was last updated
+---
+
+## Overview
+
+The Payment entity manages all payment transactions in the e-commerce system. It tracks payment details, status, and relationships with orders and customers, supporting various payment methods and refund scenarios.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Order:** Each payment belongs to one `Order` (identified by `orderId`).
+* **Customer:** Each payment is made by one `Customer` (identified by `customerId`).
+* **Address:** Each payment has a billing `Address` (identified by `billingAddress`).
+* **PaymentRefund:** A payment can have multiple `PaymentRefund` entities for partial or full refunds.
+
+## Payment States
+
+```
+pending → processing → completed
+    ↓         ↓           ↓
+cancelled  failed    refunded/partially_refunded
+```
+
+## Examples
+
+* **Payment #1:** $299.99 credit card payment for Order #12345, completed successfully.
+* **Payment #2:** $150.00 PayPal payment for Order #67890, failed due to insufficient funds.
+* **Payment #3:** $500.00 bank transfer, completed with $50.00 partial refund.
+
+## Business Rules
+
+* Payment amount must match the order total
+* Payment status transitions must follow valid state machine
+* Failed payments should include failure reason
+* Completed payments cannot be cancelled
+* Refunds cannot exceed the original payment amount
+* Payment method details are encrypted and PCI compliant
+* Transaction IDs from payment gateways must be stored for reconciliation

package/templates/default/domains/Payment/entities/PaymentMethod/index.mdx

@@ -0,0 +1,77 @@
+---
+id: PaymentMethod
+name: PaymentMethod
+version: 1.0.0
+identifier: paymentMethodId
+summary: Represents a payment instrument a customer can use, like a credit card or bank account.
+
+properties:
+  - name: paymentMethodId
+    type: UUID
+    required: true
+    description: Unique identifier for the payment method.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Identifier of the customer who owns this payment method.
+    references: Customer
+    relationType: hasOne
+  - name: type
+    type: string # (e.g., CreditCard, BankAccount, PayPal, ApplePay)
+    required: true
+    description: The type of payment method.
+  - name: details # Contains type-specific details (masked, tokenized)
+    type: object
+    required: true
+    description: Contains type-specific, often sensitive details (e.g., last 4 digits of card, card brand, bank name, account type, token). **Never store raw PANs or sensitive data.**
+    # Example structure for CreditCard:
+    # details:
+    #   brand: "Visa"
+    #   last4: "1234"
+    #   expiryMonth: 12
+    #   expiryYear: 2025
+    #   cardholderName: "Jane Doe"
+    #   gatewayToken: "tok_abc123xyz"
+  - name: isDefault
+    type: boolean
+    required: true
+    description: Indicates if this is the customer's default payment method.
+  - name: billingAddressId # Link to the billing address associated with this method
+    type: UUID
+    required: true
+    description: Identifier for the billing address verified for this payment method.
+  - name: status
+    type: string # (e.g., Active, Expired, Invalid, Removed)
+    required: true
+    description: Current status of the payment method.
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Timestamp when the payment method was added.
+  - name: updatedAt
+    type: DateTime
+    required: true
+    description: Timestamp when the payment method was last updated.
+---
+
+## Overview
+
+The PaymentMethod entity represents a specific payment instrument registered by a customer, such as a credit card or a linked bank account. It stores necessary (non-sensitive) details required to initiate payments and links to the associated customer and billing address.
+
+**Security Note:** Sensitive details like full card numbers or bank account numbers should **never** be stored directly. Rely on tokenization provided by payment gateways.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Customer:** A payment method belongs to one `Customer`.
+*   **Address:** Linked to a specific billing `Address`.
+*   **Payment:** Used to make `Payment` transactions.
+*   **Subscription:** May be designated as the payment method for a `Subscription`.
+
+## Examples
+
+*   Jane Doe's default Visa card ending in 1234, expiring 12/2025, status Active.
+*   John Smith's linked bank account (Chase, Checking), status Active.
+*   An old MasterCard ending in 5678 belonging to Jane Doe, status Expired. 

package/templates/default/domains/Payment/entities/Transaction/index.mdx

@@ -0,0 +1,77 @@
+---
+id: Transaction
+name: Transaction
+version: 1.0.0
+identifier: transactionId
+summary: Represents a low-level interaction with a payment gateway or processor (e.g., authorize, capture, refund, void).
+
+properties:
+  - name: transactionId
+    type: UUID
+    required: true
+    description: Unique identifier for this specific gateway transaction.
+  - name: paymentId
+    type: UUID
+    required: true
+    references: Payment
+    relationType: hasOne
+    description: Identifier of the parent Payment this transaction belongs to.
+  - name: type
+    type: string # (e.g., Authorize, Capture, Sale, Refund, Void, Verify)
+    required: true
+    description: The type of operation performed with the payment gateway.
+  - name: gatewayReferenceId
+    type: string
+    required: true
+    description: Unique transaction ID provided by the external payment gateway.
+  - name: amount
+    type: decimal
+    required: true
+    description: The amount associated with this specific transaction operation.
+  - name: currency
+    type: string # ISO 4217 code
+    required: true
+    description: Currency of the transaction amount.
+  - name: status
+    type: string # (e.g., Success, Failure, Pending)
+    required: true
+    description: Status reported by the gateway for this specific operation.
+  - name: responseCode # Gateway-specific code
+    type: string
+    required: false
+    description: Response code returned by the payment gateway.
+  - name: responseMessage # Gateway-specific message
+    type: string
+    required: false
+    description: Detailed message or reason returned by the gateway.
+  - name: processedAt
+    type: DateTime
+    required: true
+    description: Timestamp when the transaction was processed by the gateway.
+  - name: rawRequest # Optional, for debugging - consider security implications
+    type: text
+    required: false
+    description: Raw request payload sent to the gateway (use with caution).
+  - name: rawResponse # Optional, for debugging - consider security implications
+    type: text
+    required: false
+    description: Raw response payload received from the gateway (use with caution).
+---
+
+## Overview
+
+The Transaction entity logs the individual interactions with an external payment processor (like Stripe, PayPal, Adyen) that occur as part of processing a `Payment`. This provides a detailed audit trail of gateway operations, including authorizations, captures, refunds, and any associated success or failure responses.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Payment:** A transaction is part of one `Payment`.
+
+## Examples
+
+*   **Authorization Success:** Type: Authorize, PaymentID: PAY-98765, GatewayRef: auth_abc, Amount: $19.99, Status: Success.
+*   **Capture Success:** Type: Capture, PaymentID: PAY-98765, GatewayRef: ch_def, Amount: $19.99, Status: Success (following the authorization).
+*   **Authorization Failure:** Type: Authorize, PaymentID: PAY-98766, GatewayRef: auth_ghi, Amount: $50.00, Status: Failure, ResponseCode: 'declined', ResponseMessage: 'Insufficient Funds'.
+*   **Refund Success:** Type: Refund, PaymentID: PAY-98760, GatewayRef: re_jkl, Amount: $25.00, Status: Success. 

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

@@ -9,6 +9,16 @@ owners:
 services:
     - id: PaymentService
       version: 0.0.1
+    - id: FraudDetectionService
+      version: 0.0.1
+    - id: PaymentGatewayService
+      version: 0.0.1
+entities:
+  - id: Invoice
+  - id: Payment
+  - id: PaymentMethod
+  - id: Transaction
+  - id: Address
 badges:
     - content: Payment Domain
       backgroundColor: blue
@@ -19,6 +29,12 @@ badges:
 
 The Payment Domain encompasses all services and components related to handling financial transactions within the system. It is responsible for managing payments, transactions, billing, and financial records. The domain ensures secure, reliable, and efficient processing of all payment-related activities
 
-## Bounded context
+### Architecture for the Payment domain
 
 <NodeGraph />
+
+### Entity Map
+
+A visualization of the entities in the Payment domain. Here you can see the relationships between the entities and how they are used in the domain.
+
+<EntityMap id="Payment" />

package/templates/default/domains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/index.mdx

@@ -0,0 +1,48 @@
+---
+id: FraudCheckCompleted
+version: 0.0.1
+name: Fraud Check Completed
+summary: Emitted when a fraud check has been completed for a transaction
+tags:
+  - payment
+  - fraud
+  - security
+badges:
+  - content: New
+    backgroundColor: green
+    textColor: white
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The `FraudCheckCompleted` event is emitted when the fraud detection service has completed its analysis of a payment transaction. This event contains the risk assessment results and recommendations.
+
+## Schema
+
+<SchemaViewer title="FraudCheckCompleted Schema" schemaPath={frontmatter.schemaPath} />
+
+## Event Details
+
+- **Risk Score**: A numerical score from 0-100 indicating fraud risk
+- **Decision**: APPROVED, DECLINED, or MANUAL_REVIEW
+- **Reasons**: Array of reasons for the decision
+- **Confidence**: Confidence level of the fraud detection
+
+## Example Payload
+
+```json
+{
+  "transactionId": "txn_1234567890",
+  "paymentId": "pay_9876543210",
+  "riskScore": 25,
+  "decision": "APPROVED",
+  "reasons": ["Low risk merchant", "Customer history positive"],
+  "confidence": 0.92,
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+<Footer />

package/templates/default/domains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "transactionId": {
+      "type": "string",
+      "description": "Unique identifier for the transaction"
+    },
+    "paymentId": {
+      "type": "string",
+      "description": "Unique identifier for the payment"
+    },
+    "riskScore": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Risk score from 0-100"
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["APPROVED", "DECLINED", "MANUAL_REVIEW"],
+      "description": "Fraud check decision"
+    },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Reasons for the decision"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence level of the decision"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the fraud check was completed"
+    }
+  },
+  "required": ["transactionId", "paymentId", "riskScore", "decision", "timestamp"]
+}