Skip to main content

Commerce Checkout Workflows

Version: 1.0.0 Last Updated: December 29, 2025 Purpose: Multi-product commerce workflows for CODITECT platform including shopping cart, Google Pay, Stripe checkout, and entitlement provisioning

Table of Contents​

Product Catalog​

1. product-catalog-browse​

  • Description: Display available CODITECT products with pricing, features, and eligibility checks
  • Trigger: User visits /pricing page
  • Complexity: simple
  • Duration: 1-2s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: commerce-specialist
    • Commands: /list-products
    • APIs: GET /api/v1/products
  • Steps:
    1. Fetch products - commerce-specialist - Load product catalog from database
    2. Filter by availability - commerce-specialist - Exclude inactive/discontinued products
    3. Check user eligibility - commerce-specialist - Determine if user already owns products
    4. Calculate display prices - commerce-specialist - Apply any active promotions/discounts
    5. Render catalog - frontend - Display ProductCatalog component with ProductCards
    6. Validation - component-qa-validator - Verify all products render with correct pricing
  • Tags: [products, catalog, pricing, browse]

2. product-details-view​

  • Description: Display detailed product information including features, requirements, and related products
  • Trigger: User clicks on product card or /products/{slug}
  • Complexity: simple
  • Duration: 1-2s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: commerce-specialist
    • Commands: /get-product
    • APIs: GET /api/v1/products/{slug}
  • Steps:
    1. Fetch product - commerce-specialist - Load product details by slug
    2. Load requirements - commerce-specialist - Check product dependencies (e.g., DMS requires Core)
    3. Load related products - commerce-specialist - Fetch recommended add-ons
    4. Check ownership - commerce-specialist - Determine if user already owns this product
    5. Render details - frontend - Display full product page with add-to-cart CTA
    6. Validation - component-qa-validator - Verify all data loads correctly
  • Tags: [products, details, features, requirements]

Shopping Cart​

3. cart-add-item​

  • Description: Add a product to the shopping cart with dependency validation
  • Trigger: User clicks "Add to Cart" button
  • Complexity: moderate
  • Duration: 1-3s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: commerce-specialist, cart-manager
    • Commands: /add-to-cart
    • APIs: POST /api/v1/cart/items
  • Steps:
    1. Validate product - commerce-specialist - Verify product exists and is available
    2. Check dependencies - cart-manager - Ensure required products are in cart (e.g., Core for DMS)
    3. Check duplicates - cart-manager - Prevent adding same product twice
    4. Create/get cart - cart-manager - Get existing cart or create new one (Redis + PostgreSQL)
    5. Add item - cart-manager - Add product to cart items JSONB array
    6. Recalculate total - cart-manager - Update cart total_cents
    7. Update expiry - cart-manager - Reset 24-hour expiration
    8. Return cart - cart-manager - Return updated cart with all items
    9. Validation - component-qa-validator - Verify item added and totals correct
  • Tags: [cart, add-item, dependencies, validation]

4. cart-remove-item​

  • Description: Remove a product from the shopping cart with cascade dependency removal
  • Trigger: User clicks remove/X button on cart item
  • Complexity: moderate
  • Duration: 1-2s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: cart-manager
    • Commands: /remove-from-cart
    • APIs: DELETE /api/v1/cart/items/{item_id}
  • Steps:
    1. Validate removal - cart-manager - Check item exists in cart
    2. Check dependents - cart-manager - Find products that require this one (e.g., removing Core cascades DMS)
    3. Warn user (if cascade) - frontend - Show confirmation if removing will cascade
    4. Remove item(s) - cart-manager - Remove item and any dependent items
    5. Recalculate total - cart-manager - Update cart total_cents
    6. Return cart - cart-manager - Return updated cart
    7. Validation - component-qa-validator - Verify items removed and totals updated
  • Tags: [cart, remove-item, cascade, dependencies]

5. cart-view​

  • Description: Display current shopping cart with items, totals, and checkout options
  • Trigger: User clicks cart icon or /cart
  • Complexity: simple
  • Duration: 1-2s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: cart-manager
    • Commands: /view-cart
    • APIs: GET /api/v1/cart
  • Steps:
    1. Get cart - cart-manager - Retrieve cart by user_id or session_id
    2. Validate items - cart-manager - Ensure all products still exist and available
    3. Check expiry - cart-manager - Warn if cart expiring soon
    4. Calculate subtotals - cart-manager - Compute line item subtotals
    5. Render cart - frontend - Display ShoppingCart sidebar/page
    6. Show checkout options - frontend - Display Google Pay and Stripe buttons
    7. Validation - component-qa-validator - Verify totals match sum of items
  • Tags: [cart, view, totals, checkout-options]

6. cart-clear​

  • Description: Clear all items from shopping cart
  • Trigger: User clicks "Clear Cart" or cart expires
  • Complexity: simple
  • Duration: 1s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: cart-manager
    • Commands: /clear-cart
    • APIs: DELETE /api/v1/cart
  • Steps:
    1. Get cart - cart-manager - Retrieve current cart
    2. Clear items - cart-manager - Set items to empty array
    3. Reset total - cart-manager - Set total_cents to 0
    4. Update status - cart-manager - Set status to 'cleared' or 'expired'
    5. Clear Redis cache - cart-manager - Remove from Redis session cache
    6. Validation - component-qa-validator - Verify cart is empty
  • Tags: [cart, clear, reset]

Checkout​

7. checkout-initiate​

  • Description: Begin checkout process, validate cart, and prepare payment options
  • Trigger: User clicks "Checkout" button
  • Complexity: moderate
  • Duration: 2-5s
  • QA Integration:
    • validation: required
    • review: recommended
  • Dependencies:
    • Agents: checkout-orchestrator, cart-manager
    • Commands: /checkout
    • APIs: POST /api/v1/checkout
  • Steps:
    1. Validate cart - cart-manager - Ensure cart not empty and not expired
    2. Validate products - checkout-orchestrator - Confirm all products still available
    3. Check user auth - checkout-orchestrator - Ensure user is authenticated
    4. Validate dependencies - checkout-orchestrator - Final check that required products included
    5. Lock cart - cart-manager - Set status to 'checkout_pending'
    6. Prepare payment - checkout-orchestrator - Initialize Stripe Payment Intent
    7. Return checkout session - checkout-orchestrator - Return session ID and payment options
    8. Validation - component-qa-validator - Verify checkout session created
  • Tags: [checkout, initiate, payment-intent, validation]

8. checkout-google-pay​

  • Description: Process Google Pay one-tap checkout
  • Trigger: User taps Google Pay button
  • Complexity: complex
  • Duration: 3-10s
  • QA Integration:
    • validation: required
    • review: required
  • Dependencies:
    • Agents: checkout-orchestrator, google-pay-client, entitlement-manager
    • Commands: /checkout-google-pay
    • APIs: POST /api/v1/checkout/google-pay
  • Steps:
    1. Display Google Pay sheet - google-pay-client - Show Payment Request API
    2. User authentication - google-pay-client - User confirms with biometric/PIN
    3. Receive payment token - google-pay-client - Get encrypted payment token
    4. Create payment intent - checkout-orchestrator - Create Stripe PaymentIntent with Google Pay source
    5. Process payment - checkout-orchestrator - Charge via Stripe
    6. Verify payment - checkout-orchestrator - Confirm payment succeeded
    7. Create order - checkout-orchestrator - Record order with payment details
    8. Provision entitlements - entitlement-manager - Grant product access (see workflow #11)
    9. Clear cart - cart-manager - Set cart status to 'completed'
    10. Redirect to success - frontend - Navigate to /checkout/success
    11. Validation - component-qa-validator - Verify payment, order, and entitlements
  • Tags: [checkout, google-pay, payment, mobile]

9. checkout-stripe-redirect​

  • Description: Redirect user to Stripe Checkout for full payment flow
  • Trigger: User clicks "Pay with Card" or Google Pay unavailable
  • Complexity: complex
  • Duration: varies (user-dependent)
  • QA Integration:
    • validation: required
    • review: required
  • Dependencies:
    • Agents: checkout-orchestrator, stripe-client, entitlement-manager
    • Commands: /checkout-stripe
    • APIs: POST /api/v1/checkout (creates Stripe Checkout Session)
  • Steps:
    1. Create Stripe session - stripe-client - Generate Checkout Session with line items
    2. Set success URL - checkout-orchestrator - Configure /checkout/success?session_id={id}
    3. Set cancel URL - checkout-orchestrator - Configure /cart with cart preserved
    4. Redirect to Stripe - frontend - window.location = session.url
    5. User completes payment - stripe-client - User enters card details on Stripe
    6. Stripe webhook - stripe-client - Receive checkout.session.completed event
    7. Verify webhook signature - checkout-orchestrator - Validate Stripe signature
    8. Create order - checkout-orchestrator - Record order from webhook data
    9. Provision entitlements - entitlement-manager - Grant product access (see workflow #11)
    10. Clear cart - cart-manager - Set cart status to 'completed'
    11. Validation - component-qa-validator - Verify order and entitlements created
  • Tags: [checkout, stripe, redirect, payment, international]

10. checkout-success​

  • Description: Handle post-payment success page and display order confirmation
  • Trigger: Redirect from payment provider to /checkout/success
  • Complexity: simple
  • Duration: 2-3s
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: checkout-orchestrator
    • Commands: /order-confirmation
    • APIs: GET /api/v1/checkout/success?session_id={id}
  • Steps:
    1. Verify session - checkout-orchestrator - Confirm session_id is valid and completed
    2. Retrieve order - checkout-orchestrator - Load order by stripe_payment_intent_id
    3. Load entitlements - entitlement-manager - Get newly granted product access
    4. Display confirmation - frontend - Show order summary, receipt, next steps
    5. Send email - checkout-orchestrator - Trigger order confirmation email
    6. Track conversion - analytics - Record purchase event for analytics
    7. Validation - component-qa-validator - Verify all order details display correctly
  • Tags: [checkout, success, confirmation, email]

Entitlement Provisioning​

11. entitlement-provision​

  • Description: Grant user access to purchased products and provision resources
  • Trigger: Successful payment completion
  • Complexity: complex
  • Duration: 30s-5m (depending on products)
  • QA Integration:
    • validation: required
    • review: required
  • Dependencies:
    • Agents: entitlement-manager, workstation-provisioner, subdomain-manager
    • Commands: /provision-entitlement
    • APIs: POST /api/v1/entitlements
  • Steps:
    1. Parse order - entitlement-manager - Extract product IDs from order line_items
    2. Create entitlements - entitlement-manager - Insert entitlement records per product
    3. Check for Core - workstation-provisioner - If Core purchased, provision GCP Workstation
    4. Provision Workstation - workstation-provisioner - Create GCP Workstation instance (2-5 min)
    5. Check for DMS - subdomain-manager - If DMS purchased, enable dms.coditect.ai access
    6. Check for Workflow - subdomain-manager - If Workflow purchased, enable workflow.coditect.ai
    7. Update user permissions - entitlement-manager - Grant RBAC permissions per product
    8. Send welcome email - entitlement-manager - Product-specific onboarding instructions
    9. Validation - component-qa-validator - Verify all entitlements active and resources provisioned
  • Tags: [entitlement, provision, workstation, access-control]

12. entitlement-check​

  • Description: Verify user has valid entitlement for a product/feature
  • Trigger: User accesses product subdomain or feature
  • Complexity: simple
  • Duration: <100ms
  • QA Integration:
    • validation: required
    • review: none
  • Dependencies:
    • Agents: entitlement-manager
    • Commands: /check-entitlement
    • APIs: GET /api/v1/entitlements/{product_slug}
  • Steps:
    1. Get user context - entitlement-manager - Extract user_id from JWT
    2. Query entitlement - entitlement-manager - Check entitlements table for product
    3. Verify status - entitlement-manager - Confirm status is 'active'
    4. Check expiration - entitlement-manager - Verify subscription not expired
    5. Return result - entitlement-manager - Return boolean access grant/deny
    6. Cache result - entitlement-manager - Cache in Redis for performance (5 min TTL)
  • Tags: [entitlement, check, access-control, authorization]

13. entitlement-revoke​

  • Description: Revoke user access when subscription cancelled or refunded
  • Trigger: Subscription cancellation or refund webhook
  • Complexity: moderate
  • Duration: 5-30s
  • QA Integration:
    • validation: required
    • review: required
  • Dependencies:
    • Agents: entitlement-manager, workstation-provisioner
    • Commands: /revoke-entitlement
    • APIs: DELETE /api/v1/entitlements/{id}
  • Steps:
    1. Receive webhook - entitlement-manager - Handle customer.subscription.deleted or charge.refunded
    2. Identify entitlements - entitlement-manager - Find entitlements for this subscription
    3. Set status - entitlement-manager - Update status to 'revoked' or 'expired'
    4. Revoke subdomain access - subdomain-manager - Disable product subdomain access
    5. Handle Workstation - workstation-provisioner - Suspend (not delete) GCP Workstation
    6. Clear cache - entitlement-manager - Invalidate Redis entitlement cache
    7. Notify user - entitlement-manager - Send subscription ended notification
    8. Validation - component-qa-validator - Verify access revoked across all products
  • Tags: [entitlement, revoke, cancellation, refund]

Stripe Webhook Handling​

14. stripe-webhook-handler​

  • Description: Process incoming Stripe webhook events for payments and subscriptions
  • Trigger: POST /api/v1/webhooks/stripe
  • Complexity: complex
  • Duration: 1-5s
  • QA Integration:
    • validation: required
    • review: required
  • Dependencies:
    • Agents: checkout-orchestrator, entitlement-manager
    • Commands: /process-webhook
    • APIs: POST /api/v1/webhooks/stripe
  • Steps:
    1. Verify signature - checkout-orchestrator - Validate Stripe-Signature header
    2. Parse event - checkout-orchestrator - Extract event type and data
    3. Route by type - checkout-orchestrator - Handle based on event.type
    4. checkout.session.completed - checkout-orchestrator - Create order, provision entitlements
    5. invoice.paid - checkout-orchestrator - Extend subscription period
    6. invoice.payment_failed - checkout-orchestrator - Notify user, retry logic
    7. customer.subscription.deleted - entitlement-manager - Revoke entitlements
    8. charge.refunded - entitlement-manager - Revoke entitlements, record refund
    9. Return 200 - checkout-orchestrator - Acknowledge webhook receipt
    10. Validation - component-qa-validator - Verify event processed correctly
  • Tags: [stripe, webhook, payments, subscription]

Last Updated: December 29, 2025 Owner: CODITECT Commerce Team