@eventcatalog/create-eventcatalog 3.0.9 → 3.0.11

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

@@ -0,0 +1,59 @@
+---
+id: FraudDetectionService
+version: 0.0.1
+name: Fraud Detection Service
+summary: Analyzes payment transactions for fraudulent activity and risk assessment
+repository:
+  url: https://github.com/eventcatalog/fraud-detection-service
+receives:
+  - id: PaymentInitiated
+    version: 0.0.1
+  - id: PaymentProcessed
+    version: 0.0.1
+  - id: SubscriptionPaymentDue
+    version: 0.0.1
+sends:
+  - id: FraudCheckCompleted
+    version: 0.0.1
+  - id: FraudDetected
+    version: 0.0.1
+  - id: RiskScoreCalculated
+    version: 0.0.1
+owners:
+  - riskTeam
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The Fraud Detection Service is responsible for analyzing payment transactions in real-time to detect potential fraudulent activity. It uses machine learning models and rule-based systems to assess risk and prevent financial losses.
+
+## Key Features
+
+- **Real-time Transaction Analysis**: Analyzes transactions as they occur
+- **Machine Learning Models**: Uses ML to identify suspicious patterns
+- **Risk Scoring**: Calculates risk scores for each transaction
+- **Automated Blocking**: Can automatically block high-risk transactions
+- **Manual Review Queue**: Flags medium-risk transactions for manual review
+
+## API Endpoints
+
+### REST API
+- `POST /api/fraud/check` - Submit transaction for fraud check
+- `GET /api/fraud/risk-score/{transactionId}` - Get risk score for transaction
+- `PUT /api/fraud/override/{transactionId}` - Manual override of fraud decision
+
+## Configuration
+
+```yaml
+fraud_detection:
+  risk_thresholds:
+    high: 80
+    medium: 50
+    low: 20
+  auto_block_threshold: 90
+  ml_model_version: "2.3.1"
+```
+
+<Footer />

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

@@ -0,0 +1,72 @@
+---
+id: ProcessPayment
+version: 0.0.1
+name: Process Payment
+summary: Command to process a payment through the payment gateway
+tags:
+  - payment
+  - command
+  - cross-domain
+badges:
+  - content: Command
+    backgroundColor: blue
+    textColor: white
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The `ProcessPayment` command is used to initiate payment processing through the payment gateway. This command can be triggered by various sources including the Billing Service for subscription payments.
+
+## Command Sources
+
+This command can be triggered by:
+- **BillingService** (Subscriptions Domain) - For recurring subscription payments
+- **OrdersService** (Orders Domain) - For one-time order payments
+- **PaymentService** (Payment Domain) - For payment retries
+
+## Command Flow
+
+```mermaid
+sequenceDiagram
+    participant BS as BillingService
+    participant PGS as PaymentGatewayService
+    participant FDS as FraudDetectionService
+    participant EXT as External Gateway
+    
+    BS->>PGS: ProcessPayment
+    PGS->>FDS: Check Fraud
+    FDS-->>PGS: Risk Assessment
+    PGS->>EXT: Process Payment
+    EXT-->>PGS: Payment Result
+    PGS-->>BS: PaymentProcessed/Failed
+```
+
+## Schema
+
+<SchemaViewer title="ProcessPayment Schema" schemaPath={frontmatter.schemaPath} />
+
+## Example Request
+
+```json
+{
+  "paymentId": "pay_123456",
+  "amount": 49.99,
+  "currency": "USD",
+  "paymentMethod": {
+    "type": "card",
+    "token": "tok_visa_4242"
+  },
+  "metadata": {
+    "subscriptionId": "sub_ABC123",
+    "invoiceId": "inv_123456",
+    "customerId": "cust_XYZ789"
+  },
+  "idempotencyKey": "sub_ABC123_2024_02",
+  "captureImmediately": true
+}
+```
+
+<Footer />

package/templates/default/domains/Payment/services/PaymentGatewayService/commands/ProcessPayment/schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "paymentId": {
+      "type": "string",
+      "description": "Unique identifier for this payment"
+    },
+    "amount": {
+      "type": "number",
+      "description": "Payment amount"
+    },
+    "currency": {
+      "type": "string",
+      "description": "Currency code (ISO 4217)"
+    },
+    "paymentMethod": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["card", "bank_transfer", "paypal", "digital_wallet"]
+        },
+        "token": {
+          "type": "string",
+          "description": "Payment method token"
+        }
+      },
+      "required": ["type", "token"]
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": {
+          "type": "string"
+        },
+        "invoiceId": {
+          "type": "string"
+        },
+        "customerId": {
+          "type": "string"
+        },
+        "orderId": {
+          "type": "string"
+        }
+      }
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "description": "Key to prevent duplicate payments"
+    },
+    "captureImmediately": {
+      "type": "boolean",
+      "description": "Whether to capture payment immediately or just authorize"
+    }
+  },
+  "required": ["paymentId", "amount", "currency", "paymentMethod", "idempotencyKey"]
+}

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