@eventcatalog/create-eventcatalog 3.0.10 → 3.0.11

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

@@ -0,0 +1,154 @@
+---
+id: Review
+name: Review
+version: 1.0.0
+identifier: reviewId
+summary: Represents customer reviews and ratings for products.
+properties:
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Unique identifier for the review
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being reviewed
+    references: Product
+    referencesIdentifier: productId
+    relationType: hasOne
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who wrote the review
+    references: Customer
+    referencesIdentifier: customerId
+    relationType: hasOne
+  - name: orderId
+    type: UUID
+    required: false
+    description: Order associated with this review (for verified purchases)
+    references: Order
+    referencesIdentifier: orderId
+    relationType: hasOne
+  - name: rating
+    type: integer
+    required: true
+    description: Rating given by customer (1-5 stars)
+    minimum: 1
+    maximum: 5
+  - name: title
+    type: string
+    required: false
+    description: Review title or headline
+  - name: content
+    type: string
+    required: true
+    description: Review content and comments
+  - name: isVerifiedPurchase
+    type: boolean
+    required: true
+    description: Whether this review is from a verified purchase
+  - name: isRecommended
+    type: boolean
+    required: false
+    description: Whether customer recommends this product
+  - name: helpfulVotes
+    type: integer
+    required: true
+    description: Number of helpful votes received
+  - name: totalVotes
+    type: integer
+    required: true
+    description: Total number of votes received
+  - name: status
+    type: string
+    required: true
+    description: Current review status
+    enum: ['pending', 'approved', 'rejected', 'flagged']
+  - name: moderationNotes
+    type: string
+    required: false
+    description: Internal moderation notes
+  - name: images
+    type: array
+    items:
+      type: string
+    required: false
+    description: URLs of images uploaded with the review
+  - name: pros
+    type: array
+    items:
+      type: string
+    required: false
+    description: List of positive aspects mentioned
+  - name: cons
+    type: array
+    items:
+      type: string
+    required: false
+    description: List of negative aspects mentioned
+  - name: merchantResponse
+    type: object
+    required: false
+    description: Response from merchant to this review
+    properties:
+      - name: content
+        type: string
+        description: Merchant response content
+      - name: respondedAt
+        type: DateTime
+        description: When merchant responded
+      - name: respondedBy
+        type: string
+        description: Who responded for the merchant
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Date and time when the review was created
+  - name: updatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the review was last updated
+  - name: moderatedAt
+    type: DateTime
+    required: false
+    description: Date and time when the review was moderated
+---
+
+## Overview
+
+The Review entity captures customer feedback and ratings for products. It supports verified purchase validation, content moderation, community voting, and merchant responses to build trust and provide valuable product insights.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+* **Product:** Each review belongs to one `Product` (identified by `productId`).
+* **Customer:** Each review is written by one `Customer` (identified by `customerId`).
+* **Order:** Each review can be linked to one `Order` for purchase verification (identified by `orderId`).
+
+## Review Lifecycle
+
+```
+submitted → pending → approved → published
+              ↓         ↓
+           rejected   flagged
+```
+
+## Examples
+
+* **Review #1:** 5-star review for iPhone 15 Pro, verified purchase, "Excellent camera quality!"
+* **Review #2:** 3-star review for Running Shoes, helpful votes: 15/20, includes photos
+* **Review #3:** 1-star review flagged for inappropriate content, pending moderation
+
+## Business Rules
+
+* Reviews can only be submitted by customers who purchased the product
+* Rating must be between 1-5 stars
+* Verified purchase reviews are given higher weight in calculations
+* Inappropriate content is flagged and requires moderation
+* Customers can only review the same product once per purchase
+* Helpful votes help surface most valuable reviews
+* Merchant responses are limited to one per review
+* Reviews older than 2 years may have reduced weight in calculations

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

@@ -0,0 +1,74 @@
+---
+id: ProductCatalog
+name: Product Catalog
+version: 0.0.1
+summary: Manages product information, categories, inventory, and customer reviews in the e-commerce system.
+owners:
+  - dboyne
+entities:
+  - id: Product
+  - id: Category
+  - id: Inventory
+  - id: Review
+services:
+  - id: ProductService
+  - id: CategoryService
+  - id: InventoryService
+  - id: ReviewService
+---
+
+## Overview
+
+The Product Catalog subdomain is responsible for managing all product-related information in the e-commerce system. This includes product details, hierarchical categorization, inventory tracking, and customer reviews.
+
+### Architecture for the Product Catalog domain
+
+<NodeGraph />
+
+### Entity Map
+
+A visualization of the entities in the Product Catalog domain. Here you can see the relationships between the entities and how they are used in the domain.
+
+<EntityMap id="ProductCatalog" />
+
+
+
+## Core Responsibilities
+
+### Product Management
+- Maintain product information including pricing, descriptions, and specifications
+- Support product variants (size, color, style)
+- Handle product lifecycle (active, discontinued, draft)
+- Manage product relationships and cross-selling
+
+### Category Management  
+- Organize products into hierarchical categories
+- Support multi-level category structures
+- Maintain category metadata and SEO information
+- Handle category navigation and filtering
+
+### Inventory Management
+- Track stock levels and availability
+- Manage reorder points and stock alerts  
+- Handle inventory reservations and allocations
+- Support warehouse and location management
+
+### Review Management
+- Collect and manage customer product reviews
+- Calculate review metrics and ratings
+- Moderate review content
+- Support review helpfulness and responses
+
+## Key Entities
+
+- **Product**: Central aggregate containing all product information
+- **Category**: Hierarchical product categorization system
+- **Inventory**: Stock tracking and availability management  
+- **Review**: Customer feedback and rating system
+
+## Business Rules
+
+- Products must belong to an active category
+- Inventory levels affect product availability
+- Reviews require verified purchases
+- Category hierarchies have maximum depth limits

package/templates/default/domains/Subscriptions/entities/BillingProfile/index.mdx

@@ -0,0 +1,68 @@
+---
+id: BillingProfile
+name: BillingProfile
+version: 1.0.0
+identifier: billingProfileId
+summary: Stores billing-related contact information and preferences for a customer, often used for invoices and communication.
+
+properties:
+  - name: billingProfileId
+    type: UUID
+    required: true
+    description: Unique identifier for the billing profile.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Identifier of the customer this billing profile belongs to.
+    references: Customer
+    referencesIdentifier: customerId
+    relationType: hasOne
+  - name: billingEmail
+    type: string
+    required: false # May default to customer's primary email
+    description: Specific email address for sending invoices and billing notifications
+  - name: companyName # Optional, for B2B
+    type: string
+    required: false
+    description: Company name for billing purposes.
+  - name: taxId # Optional, for B2B or specific regions
+    type: string
+    required: false
+    description: Tax identification number (e.g., VAT ID, EIN).
+  - name: billingAddressId
+    type: UUID
+    required: true
+    description: Identifier for the primary billing address associated with this profile.
+  - name: preferredPaymentMethodId # Optional default for invoices/subscriptions
+    type: UUID
+    required: false
+    description: Customer's preferred payment method for charges related to this profile.
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Timestamp when the billing profile was created.
+  - name: updatedAt
+    type: DateTime
+    required: true
+    description: Timestamp when the billing profile was last updated.
+---
+
+## Overview
+
+The BillingProfile entity consolidates billing-specific details for a customer, such as the billing address, contact email for invoices, tax information, and potentially preferred payment methods. This might be distinct from the customer's general contact information or shipping addresses.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Customer:** A billing profile belongs to one `Customer`. A customer might potentially have multiple profiles in complex scenarios, but often just one.
+*   **Address:** Linked to a primary billing `Address`.
+*   **PaymentMethod:** May specify a preferred `PaymentMethod`.
+*   **Invoice:** Invoices are typically generated using information from the BillingProfile.
+*   **Subscription:** Subscriptions may use the associated customer's BillingProfile for charging.
+
+## Examples
+
+*   Jane Doe's personal billing profile with her home address and primary email.
+*   Acme Corp's billing profile with their HQ address, VAT ID, and accounts payable email address. 

package/templates/default/domains/Subscriptions/entities/SubscriptionPeriod/index.mdx

@@ -0,0 +1,73 @@
+---
+id: SubscriptionPeriod
+name: SubscriptionPeriod
+version: 1.0.0
+identifier: subscriptionPeriodId
+summary: Represents a single billing cycle or interval within a subscription's lifetime.
+
+properties:
+  - name: subscriptionPeriodId
+    type: UUID
+    required: true
+    description: Unique identifier for this specific subscription period.
+  - name: subscriptionId
+    type: UUID
+    required: true
+    description: Identifier of the parent Subscription this period belongs to.
+  - name: planId # Denormalized for easier lookup?
+    type: UUID
+    required: true
+    description: Identifier of the Plan active during this period
+  - name: startDate
+    type: Date
+    required: true
+    description: The start date of this billing period.
+  - name: endDate
+    type: Date
+    required: true
+    description: The end date of this billing period.
+  - name: invoiceId # Optional, links to the invoice generated for this period
+    type: UUID
+    required: false
+    description: Identifier of the invoice created for this period's charge.
+  - name: paymentId # Optional, links to the payment made for this period's invoice
+    type: UUID
+    required: false
+    description: Identifier of the payment that settled the invoice for this period.
+  - name: status
+    type: string # (e.g., Active, Billed, Paid, Unpaid, PastDue)
+    required: true
+    description: Status specific to this period (reflects invoicing/payment state).
+  - name: amountBilled
+    type: decimal
+    required: false # May only be set once invoiced
+    description: The actual amount billed for this period (could differ from plan due to promotions, usage, etc.).
+  - name: currency
+    type: string # ISO 4217 code
+    required: false
+    description: Currency of the billed amount.
+  - name: createdAt
+    type: DateTime
+    required: true
+    description: Timestamp when this period record was created (often at the start of the period).
+---
+
+## Overview
+
+The SubscriptionPeriod entity tracks the state and details of a specific billing cycle within a `Subscription`. It links the subscription to the relevant invoice and payment for that interval and records the exact dates and amount billed.
+
+### Entity Properties
+<EntityPropertiesTable />
+
+## Relationships
+
+*   **Subscription:** A subscription period belongs to one `Subscription`.
+*   **Plan:** Reflects the `Plan` active during this period.
+*   **Invoice:** May be associated with one `Invoice` generated for this period.
+*   **Payment:** May be associated with one `Payment` that settled the period's invoice.
+
+## Examples
+
+*   Period for Jane Doe's 'Pro Plan' from 2024-05-01 to 2024-05-31, invoiced via #INV-00123, status Paid.
+*   Period for Acme Corp's 'Enterprise Plan' from 2024-04-15 to 2024-05-14, status Billed, awaiting payment.
+*   The first period (trial) for a new subscription from 2024-05-20 to 2024-06-19, status Active, amountBilled $0.00. 

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

@@ -7,8 +7,13 @@ summary: |
 owners:
     - dboyne
 services:
-    - id: SubscriptionService
+    - id: BillingService
       version: 0.0.1
+    - id: PlanManagementService
+      version: 0.0.1
+entities:
+    - id: BillingProfile
+    - id: SubscriptionPeriod
 badges:
     - content: Payment Domain
       backgroundColor: blue
@@ -19,6 +24,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 Subscription domain
 
 <NodeGraph />
+
+### Entity Map
+
+A visualization of the entities in the Subscription domain. Here you can see the relationships between the entities and how they are used in the domain.
+
+<EntityMap id="Subscription" />

package/templates/default/domains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/index.mdx

@@ -0,0 +1,60 @@
+---
+id: SubscriptionPaymentDue
+version: 0.0.1
+name: Subscription Payment Due
+summary: Emitted when a subscription payment is due for collection
+tags:
+  - billing
+  - payment
+  - cross-domain
+badges:
+  - content: Cross-Domain
+    backgroundColor: purple
+    textColor: white
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The `SubscriptionPaymentDue` event is emitted by the Billing Service when a subscription's billing cycle is due for payment. This event triggers the payment collection process in the Payment domain.
+
+## Cross-Domain Communication
+
+This event facilitates communication between:
+- **Source**: Subscriptions Domain (BillingService)
+- **Target**: Payment Domain (PaymentService, FraudDetectionService)
+
+## Schema
+
+<SchemaViewer title="SubscriptionPaymentDue Schema" schemaPath={frontmatter.schemaPath} />
+
+## Event Flow
+
+1. BillingService calculates when payment is due
+2. Emits `SubscriptionPaymentDue` event
+3. PaymentService receives and initiates payment
+4. FraudDetectionService performs risk assessment
+5. Payment is processed through PaymentGatewayService
+
+## Example Payload
+
+```json
+{
+  "subscriptionId": "sub_ABC123",
+  "customerId": "cust_XYZ789",
+  "invoiceId": "inv_123456",
+  "amount": 49.99,
+  "currency": "USD",
+  "dueDate": "2024-02-01T00:00:00Z",
+  "billingPeriod": {
+    "start": "2024-02-01",
+    "end": "2024-02-29"
+  },
+  "planId": "pro-monthly",
+  "retryAttempt": 0
+}
+```
+
+<Footer />

package/templates/default/domains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "subscriptionId": {
+      "type": "string",
+      "description": "Unique identifier for the subscription"
+    },
+    "customerId": {
+      "type": "string",
+      "description": "Unique identifier for the customer"
+    },
+    "invoiceId": {
+      "type": "string",
+      "description": "Unique identifier for the invoice"
+    },
+    "amount": {
+      "type": "number",
+      "description": "Amount due for payment"
+    },
+    "currency": {
+      "type": "string",
+      "description": "Currency code (ISO 4217)"
+    },
+    "dueDate": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the payment is due"
+    },
+    "billingPeriod": {
+      "type": "object",
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date"
+        },
+        "end": {
+          "type": "string",
+          "format": "date"
+        }
+      },
+      "required": ["start", "end"]
+    },
+    "planId": {
+      "type": "string",
+      "description": "Subscription plan identifier"
+    },
+    "retryAttempt": {
+      "type": "integer",
+      "description": "Number of retry attempts for failed payments"
+    }
+  },
+  "required": ["subscriptionId", "customerId", "invoiceId", "amount", "currency", "dueDate"]
+}

package/templates/default/domains/Subscriptions/services/BillingService/index.mdx

@@ -0,0 +1,86 @@
+---
+id: BillingService
+version: 0.0.1
+name: Billing Service
+summary: Manages billing cycles, invoice generation, and payment scheduling for subscriptions
+tags:
+  - billing
+  - subscriptions
+  - invoicing
+repository:
+  url: https://github.com/eventcatalog/billing-service
+receives:
+  - id: SubscriptionCreated
+    version: 0.0.1
+  - id: SubscriptionUpdated
+    version: 0.0.1
+  - id: PaymentProcessed
+    version: 0.0.1
+  - id: PaymentFailed
+    version: 0.0.1
+sends:
+  - id: InvoiceGenerated
+    version: 0.0.1
+  - id: SubscriptionPaymentDue
+    version: 0.0.1
+  - id: BillingCycleCompleted
+    version: 0.0.1
+  - id: ProcessPayment
+    version: 0.0.1
+owners:
+  - billingTeam
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The Billing Service is responsible for managing all billing-related operations for subscriptions. It calculates billing cycles, generates invoices, and coordinates with payment services to ensure timely payment collection.
+
+## Key Features
+
+- **Billing Cycle Management**: Handles daily, weekly, monthly, quarterly, and annual billing cycles
+- **Invoice Generation**: Creates detailed invoices with line items and tax calculations
+- **Payment Scheduling**: Schedules recurring payments based on billing cycles
+- **Proration**: Calculates prorated charges for mid-cycle changes
+- **Dunning Management**: Handles failed payment retry logic
+
+## API Endpoints
+
+### REST API
+- `GET /api/billing/invoice/{subscriptionId}` - Get current invoice
+- `GET /api/billing/history/{subscriptionId}` - Get billing history
+- `POST /api/billing/preview` - Preview upcoming charges
+- `PUT /api/billing/retry/{invoiceId}` - Retry failed payment
+
+## Billing Cycle States
+
+```mermaid
+stateDiagram-v2
+    [*] --> Scheduled
+    Scheduled --> Processing
+    Processing --> Paid
+    Processing --> Failed
+    Failed --> Retrying
+    Retrying --> Paid
+    Retrying --> Suspended
+    Paid --> [*]
+    Suspended --> [*]
+```
+
+## Configuration
+
+```yaml
+billing_service:
+  cycles:
+    - daily
+    - weekly
+    - monthly
+    - quarterly
+    - annual
+  retry_attempts: 3
+  retry_interval_days: [1, 3, 7]
+  invoice_generation_lead_days: 7
+```
+
+<Footer />

package/templates/default/domains/Subscriptions/services/PlanManagementService/index.mdx

@@ -0,0 +1,93 @@
+---
+id: PlanManagementService
+version: 0.0.1
+name: Plan Management Service
+summary: Manages subscription plans, features, pricing tiers, and plan migrations
+tags:
+  - plans
+  - pricing
+  - subscriptions
+repository:
+  url: https://github.com/eventcatalog/plan-management-service
+receives:
+  - id: CreatePlan
+    version: 0.0.1
+  - id: UpdatePlan
+    version: 0.0.1
+  - id: MigratePlan
+    version: 0.0.1
+sends:
+  - id: PlanCreated
+    version: 0.0.1
+  - id: PlanUpdated
+    version: 0.0.1
+  - id: PlanMigrationCompleted
+    version: 0.0.1
+  - id: FeatureAccessChanged
+    version: 0.0.1
+owners:
+  - productTeam
+---
+
+import Footer from '@catalog/components/footer.astro'
+
+## Overview
+
+The Plan Management Service handles the definition and management of subscription plans, including pricing, features, and plan migrations. It serves as the source of truth for what features and limits apply to each subscription tier.
+
+## Key Features
+
+- **Plan Definition**: Create and manage subscription plans with different tiers
+- **Feature Flags**: Control feature access based on subscription plans
+- **Usage Limits**: Define and enforce usage limits per plan
+- **Plan Migration**: Handle upgrades and downgrades between plans
+- **Pricing Management**: Manage pricing, discounts, and promotional offers
+
+## Supported Plan Types
+
+### Basic Plan
+- Essential features
+- Limited usage quotas
+- Email support
+
+### Professional Plan
+- All Basic features
+- Higher usage quotas
+- Priority support
+- Advanced analytics
+
+### Enterprise Plan
+- All Professional features
+- Unlimited usage
+- Dedicated support
+- Custom integrations
+- SLA guarantees
+
+## API Endpoints
+
+### REST API
+- `GET /api/plans` - List all available plans
+- `GET /api/plans/{planId}` - Get plan details
+- `POST /api/plans` - Create new plan
+- `PUT /api/plans/{planId}` - Update plan
+- `POST /api/plans/migrate` - Migrate subscription to different plan
+
+## Plan Structure
+
+```json
+{
+  "id": "pro-monthly",
+  "name": "Professional Monthly",
+  "price": 49.99,
+  "currency": "USD",
+  "interval": "monthly",
+  "features": {
+    "api_calls": 10000,
+    "storage_gb": 100,
+    "team_members": 10,
+    "priority_support": true
+  }
+}
+```
+
+<Footer />