@eventcatalog/create-eventcatalog 3.0.10 → 3.0.11

package/templates/default/domains/Payment/services/PaymentGatewayService/events/PaymentFailed/index.mdx

@@ -0,0 +1,60 @@
+---
+id: PaymentFailed
+version: 0.0.1
+name: Payment Failed
+summary: Emitted when a payment attempt fails
+badges:
+  - content: Error Event
+    backgroundColor: red
+    textColor: white
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The `PaymentFailed` event is emitted when a payment attempt fails for any reason. This event is consumed by various services to handle payment failures appropriately.
+
+## Consumers
+
+This event is consumed by:
+- **BillingService** (Subscriptions Domain) - To handle subscription payment failures
+- **OrdersService** (Orders Domain) - To handle order payment failures
+- **NotificationService** (Orders Domain) - To notify customers of payment failures
+
+## Failure Reasons
+
+Common failure reasons include:
+- **insufficient_funds** - Card has insufficient funds
+- **card_declined** - Card was declined by issuer
+- **expired_card** - Card has expired
+- **fraud_suspected** - Payment flagged as potentially fraudulent
+- **network_error** - Payment gateway network error
+- **invalid_payment_method** - Payment method is invalid
+
+## Schema
+
+<SchemaViewer title="PaymentFailed Schema" schemaPath={frontmatter.schemaPath} />
+
+## Example Payload
+
+```json
+{
+  "paymentId": "pay_123456",
+  "amount": 49.99,
+  "currency": "USD",
+  "failureReason": "insufficient_funds",
+  "failureMessage": "Your card has insufficient funds",
+  "metadata": {
+    "subscriptionId": "sub_ABC123",
+    "invoiceId": "inv_123456",
+    "customerId": "cust_XYZ789"
+  },
+  "canRetry": true,
+  "nextRetryAt": "2024-02-02T00:00:00Z",
+  "timestamp": "2024-02-01T10:30:00Z"
+}
+```
+
+<Footer />

package/templates/default/domains/Payment/services/PaymentGatewayService/events/PaymentFailed/schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "paymentId": {
+      "type": "string",
+      "description": "Unique identifier for the failed payment"
+    },
+    "amount": {
+      "type": "number",
+      "description": "Payment amount that failed"
+    },
+    "currency": {
+      "type": "string",
+      "description": "Currency code (ISO 4217)"
+    },
+    "failureReason": {
+      "type": "string",
+      "enum": [
+        "insufficient_funds",
+        "card_declined",
+        "expired_card",
+        "fraud_suspected",
+        "network_error",
+        "invalid_payment_method",
+        "authentication_required",
+        "other"
+      ],
+      "description": "Reason for payment failure"
+    },
+    "failureMessage": {
+      "type": "string",
+      "description": "Human-readable failure message"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": {
+          "type": "string"
+        },
+        "invoiceId": {
+          "type": "string"
+        },
+        "customerId": {
+          "type": "string"
+        },
+        "orderId": {
+          "type": "string"
+        }
+      }
+    },
+    "canRetry": {
+      "type": "boolean",
+      "description": "Whether this payment can be retried"
+    },
+    "nextRetryAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Suggested time for next retry attempt"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the failure occurred"
+    }
+  },
+  "required": ["paymentId", "amount", "currency", "failureReason", "timestamp"]
+}

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

@@ -0,0 +1,78 @@
+---
+id: PaymentGatewayService
+version: 0.0.1
+name: Payment Gateway Service
+summary: Manages integration with external payment processors (Stripe, PayPal, etc.)
+tags:
+  - payment
+  - gateway
+  - integration
+repository:
+  url: https://github.com/eventcatalog/payment-gateway-service
+receives:
+  - id: ProcessPayment
+    version: 0.0.1
+  - id: RefundPayment
+    version: 0.0.1
+  - id: FraudCheckCompleted
+    version: 0.0.1
+sends:
+  - id: PaymentAuthorized
+    version: 0.0.1
+  - id: PaymentCaptured
+    version: 0.0.1
+  - id: PaymentFailed
+    version: 0.0.1
+  - id: RefundProcessed
+    version: 0.0.1
+owners:
+  - paymentsTeam
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The Payment Gateway Service acts as an abstraction layer between our payment system and external payment processors. It handles the complexity of integrating with multiple payment providers and provides a unified interface for payment operations.
+
+## Supported Payment Providers
+
+- **Stripe**: Credit/debit cards, digital wallets
+- **PayPal**: PayPal accounts, PayPal Credit
+- **Square**: In-person and online payments
+- **Adyen**: Global payment processing
+- **Braintree**: Multiple payment methods
+
+## Key Features
+
+- **Multi-provider Support**: Switch between providers seamlessly
+- **Retry Logic**: Automatic retry for failed transactions
+- **Tokenization**: Secure card data handling
+- **Webhook Management**: Handles provider webhooks
+- **Currency Conversion**: Support for 150+ currencies
+
+## API Endpoints
+
+### REST API
+- `POST /api/gateway/authorize` - Authorize a payment
+- `POST /api/gateway/capture` - Capture an authorized payment
+- `POST /api/gateway/refund` - Process a refund
+- `GET /api/gateway/status/{transactionId}` - Get transaction status
+
+## Configuration
+
+```yaml
+payment_gateway:
+  providers:
+    stripe:
+      api_key: ${STRIPE_API_KEY}
+      webhook_secret: ${STRIPE_WEBHOOK_SECRET}
+    paypal:
+      client_id: ${PAYPAL_CLIENT_ID}
+      client_secret: ${PAYPAL_CLIENT_SECRET}
+  retry:
+    max_attempts: 3
+    backoff_ms: 1000
+```
+
+<Footer />

package/templates/default/domains/ProductCatalog/entities/Category/index.mdx

@@ -0,0 +1,124 @@
+---
+id: Category
+name: Category
+version: 1.0.0
+identifier: categoryId
+aggregateRoot: true
+summary: Represents a product category with hierarchical structure support.
+properties:
+  - name: categoryId
+    type: UUID
+    required: true
+    description: Unique identifier for the category
+  - name: name
+    type: string
+    required: true
+    description: Name of the category
+  - name: description
+    type: string
+    required: false
+    description: Description of the category
+  - name: slug
+    type: string
+    required: true
+    description: URL-friendly identifier for the category
+  - name: parentCategoryId
+    type: UUID
+    required: false
+    description: Parent category for hierarchical structure
+    references: Category
+    referencesIdentifier: categoryId
+    relationType: hasOne
+  - name: childCategories
+    type: array
+    items:
+      type: Category
+    required: false
+    description: Subcategories under this category
+    references: Category
+    referencesIdentifier: parentCategoryId
+    relationType: hasMany
+  - name: level
+    type: integer
+    required: true
+    description: Depth level in the category hierarchy (0 = root)
+  - name: isActive
+    type: boolean
+    required: true
+    description: Whether the category is currently active
+  - name: sortOrder
+    type: integer
+    required: false
+    description: Display order within the same level
+  - name: icon
+    type: string
+    required: false
+    description: Icon URL or identifier for the category
+  - name: imageUrl
+    type: string
+    required: false
+    description: Category banner or thumbnail image
+  - name: seoTitle
+    type: string
+    required: false
+    description: SEO-optimized title for the category page
+  - name: seoDescription
+    type: string
+    required: false
+    description: SEO meta description for the category page
+  - name: products
+    type: array
+    items:
+      type: Product
+    required: false
+    description: Products belonging to this category
+    references: Product
+    referencesIdentifier: categoryId
+    relationType: hasMany
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the category was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the category was last updated
+---
+
+## Overview
+
+The Category entity organizes products into a hierarchical structure, supporting multi-level categorization. It enables efficient product discovery and navigation through the e-commerce catalog.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Parent Category:** Each category can have one parent `Category` (identified by `parentCategoryId`).
+* **Child Categories:** A category can have multiple child `Category` entities creating a hierarchy.
+* **Products:** A category contains multiple `Product` entities (identified by `categoryId`).
+
+## Hierarchy Examples
+
+```
+Electronics (Level 0)
+├── Computers (Level 1)
+│   ├── Laptops (Level 2)
+│   ├── Desktops (Level 2)
+│   └── Tablets (Level 2)
+├── Mobile Phones (Level 1)
+│   ├── Smartphones (Level 2)
+│   └── Feature Phones (Level 2)
+└── Audio (Level 1)
+    ├── Headphones (Level 2)
+    └── Speakers (Level 2)
+```
+
+## Business Rules
+
+* Root categories have `parentCategoryId` as null and `level` as 0
+* Child categories must have a valid `parentCategoryId`
+* Category slugs must be unique across the entire catalog
+* Categories cannot be deleted if they contain products or subcategories
+* Inactive categories should hide all associated products from public view
+* Maximum hierarchy depth should be limited (e.g., 5 levels)

package/templates/default/domains/ProductCatalog/entities/Inventory/index.mdx

@@ -0,0 +1,116 @@
+---
+id: Inventory
+name: Inventory
+version: 1.0.0
+identifier: inventoryId
+summary: Tracks stock levels and availability for products.
+properties:
+  - name: inventoryId
+    type: UUID
+    required: true
+    description: Unique identifier for the inventory record
+  - name: productId
+    type: UUID
+    required: true
+    description: Product this inventory record tracks
+    references: Product
+    referencesIdentifier: productId
+    relationType: hasOne
+  - name: sku
+    type: string
+    required: true
+    description: Stock Keeping Unit matching the product SKU
+  - name: quantityOnHand
+    type: integer
+    required: true
+    description: Current available stock quantity
+  - name: quantityReserved
+    type: integer
+    required: true
+    description: Quantity reserved for pending orders
+  - name: quantityAvailable
+    type: integer
+    required: true
+    description: Calculated available quantity (onHand - reserved)
+  - name: minimumStockLevel
+    type: integer
+    required: true
+    description: Minimum stock level before reorder alert
+  - name: maximumStockLevel
+    type: integer
+    required: false
+    description: Maximum stock level for inventory management
+  - name: reorderPoint
+    type: integer
+    required: true
+    description: Stock level that triggers reorder process
+  - name: reorderQuantity
+    type: integer
+    required: true
+    description: Quantity to order when restocking
+  - name: unitCost
+    type: decimal
+    required: false
+    description: Cost per unit for inventory valuation
+  - name: warehouseLocation
+    type: string
+    required: false
+    description: Physical location or bin where item is stored
+  - name: lastRestockedAt
+    type: DateTime
+    required: false
+    description: Date and time of last restock
+  - name: lastSoldAt
+    type: DateTime
+    required: false
+    description: Date and time of last sale
+  - name: isTrackingEnabled
+    type: boolean
+    required: true
+    description: Whether inventory tracking is enabled for this product
+  - name: backorderAllowed
+    type: boolean
+    required: true
+    description: Whether backorders are allowed when out of stock
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the inventory record was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the inventory record was last updated
+---
+
+## Overview
+
+The Inventory entity manages stock levels and availability for products in the e-commerce system. It tracks current quantities, reserved stock, and provides reorder management capabilities.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Product:** Each inventory record belongs to one `Product` (identified by `productId`).
+* **OrderItem:** Inventory quantities are affected by `OrderItem` entities when orders are placed.
+
+## Stock Calculations
+
+* **Available Quantity** = Quantity On Hand - Quantity Reserved
+* **Reorder Needed** = Quantity Available &lt;= Reorder Point
+* **Stock Value** = Quantity On Hand × Unit Cost
+
+## Examples
+
+* **Inventory #1:** iPhone 15 Pro - 25 on hand, 5 reserved, 20 available, reorder at 10 units.
+* **Inventory #2:** Running Shoes Size 9 - 0 on hand, 2 reserved, backorder allowed.
+
+## Business Rules
+
+* Quantity on hand cannot be negative
+* Quantity reserved cannot exceed quantity on hand
+* Available quantity is automatically calculated
+* Reorder alerts are triggered when available = reorder point
+* Stock reservations are created when orders are placed
+* Stock is decremented when orders are shipped
+* Inventory adjustments must be logged for audit trail

package/templates/default/domains/ProductCatalog/entities/Product/index.mdx

@@ -0,0 +1,115 @@
+---
+id: Product
+name: Product
+version: 1.0.0
+identifier: productId
+aggregateRoot: true
+summary: Represents a product or service available for purchase in the e-commerce system.
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Unique identifier for the product
+  - name: name
+    type: string
+    required: true
+    description: Name of the product
+  - name: description
+    type: string
+    required: false
+    description: Detailed description of the product
+  - name: sku
+    type: string
+    required: true
+    description: Stock Keeping Unit - unique product identifier
+  - name: price
+    type: decimal
+    required: true
+    description: Current selling price of the product
+  - name: categoryId
+    type: UUID
+    required: true
+    description: Category this product belongs to
+    references: Category
+    referencesIdentifier: categoryId
+    relationType: hasOne
+  - name: brand
+    type: string
+    required: false
+    description: Brand name of the product
+  - name: weight
+    type: decimal
+    required: false
+    description: Weight of the product in kilograms
+  - name: dimensions
+    type: object
+    required: false
+    description: Product dimensions (length, width, height)
+    properties:
+      - name: length
+        type: decimal
+      - name: width
+        type: decimal
+      - name: height
+        type: decimal
+  - name: isActive
+    type: boolean
+    required: true
+    description: Whether the product is currently available for sale
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the product was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the product was last updated
+  - name: images
+    type: array
+    items:
+      type: string
+    required: false
+    description: URLs of product images
+  - name: inventory
+    type: Inventory
+    required: false
+    description: Inventory information for this product
+    references: Inventory
+    referencesIdentifier: productId
+    relationType: hasOne
+  - name: reviews
+    type: array
+    items:
+      type: Review
+    required: false
+    description: Customer reviews for this product
+    references: Review
+    referencesIdentifier: productId
+    relationType: hasMany
+---
+
+## Overview
+
+The Product entity represents items or services available for purchase in the e-commerce system. It serves as an aggregate root containing all product-related information including pricing, categorization, inventory details, and customer reviews.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Category:** Each product belongs to one `Category` (identified by `categoryId`).
+* **Inventory:** Each product has one `Inventory` record tracking stock levels.
+* **Review:** A product can have multiple `Review` entities from customers.
+* **OrderItem:** Products are referenced in `OrderItem` entities when included in orders.
+
+## Examples
+
+* **Product #1:** "iPhone 15 Pro" - Electronics category, $999.99, with 50 units in stock and 4.5-star reviews.
+* **Product #2:** "Running Shoes" - Sports category, $129.99, various sizes available, with detailed size chart.
+
+## Business Rules
+
+* Products must have a unique SKU across the entire catalog
+* Products cannot be deleted if they have associated order items
+* Price changes should be tracked for audit purposes
+* Products must belong to an active category to be purchasable