Byte Customer Order Flow and Dependencies

The complete customer ordering happy path across the Byte Platform, from authentication to order confirmation.

sequenceDiagram
    participant C as Customer App
    participant GW as Ordering Gateway
    participant IDP as idpservice
    participant SM as store-menu-dgs
    participant Cart as go-cart-dgs
    participant Promo as promotions-dgs
    participant Tax as tax-dgs
    participant Loy as loyalty-dgs
    participant Del as delivery-dgs
    participant Pay as payment-dgs
    participant Ord as order-dgs
    participant WF as workflowservice
    participant PWF as payment-workflowservice
    participant POS as Brand POS/Middleware

    Note over C,POS: Phase 1: Authentication
    C->>GW: Login request
    GW->>IDP: Authenticate (OAuth2/OTP/Social)
    IDP-->>GW: Access + Refresh tokens
    GW-->>C: Authenticated session

    Note over C,POS: Phase 2: Browse & Select
    C->>GW: Get store menu
    GW->>SM: Store lookup + menu retrieval
    SM-->>GW: Menu data (from S3 cache)
    GW-->>C: Store menu displayed

    Note over C,POS: Phase 3: Build Cart
    C->>GW: Add items to cart
    GW->>Cart: addLineItemsToCart
    Cart->>Promo: calculatePromotionsForCart
    Cart->>Tax: calculateCartTax
    Cart->>Del: storeDeliveryProviders (if delivery)
    Cart->>Loy: getCustomerLoyalty (if loyalty member)
    Promo-->>Cart: Promotions applied
    Tax-->>Cart: Tax calculated
    Del-->>Cart: Delivery options
    Loy-->>Cart: Loyalty points/rewards
    Cart-->>GW: Complete cart with pricing
    GW-->>C: Cart displayed

    Note over C,POS: Phase 4: Payment
    C->>GW: Submit payment
    GW->>Pay: beginPaymentSession
    Pay->>Pay: authorizePayment (Fiserv/Cybersource)
    Pay-->>GW: Payment authorized
    GW-->>C: Payment confirmed

    Note over C,POS: Phase 5: Order Submission
    C->>GW: Submit order
    GW->>Ord: submitOrder
    Ord->>WF: Start order workflow (Temporal)
    WF->>POS: Transmit order to brand
    POS-->>WF: Order confirmed/rejected
    WF->>PWF: Trigger payment capture
    PWF->>Pay: capturePayment
    WF-->>Ord: Order status updated
    Ord-->>GW: Order confirmation
    GW-->>C: Order confirmed

Service: idpservice

The customer authenticates via one of several methods:

• Email/Password: Traditional login
• OTP (One-Time Password): SMS or email code
• Social Login: Google, Apple, Facebook OAuth
• Magic Link: Email-based passwordless login
• Token Refresh: Automatic session renewal

Brand Variations

Key Telemetry

• service:idpservice @evt.name:oauth-token-post - Token grant events
• service:idpservice @event.outcome:failure - Auth failures
• @metadata.grant_type - OAuth grant type (authorization_code, client_credentials, refresh_token)
• @metadata.flow_type - Login flow (emailMagicLink, otp, social)

Services: store-menu-dgs, customer-dgs

Customer selects a store and browses the menu. Store-menu-dgs retrieves menu data from S3 cache (pre-published by menu-workflowservice).

Key Facts

• store-menu-dgs is heavily sampled (~1% log sampling rate) - actual traffic is much higher than 51K logs/hr suggests
• Menu data is served from S3 cache, not computed on the fly
• Store lookup includes geolocation, hours, availability
• Menu varies by store group, brand, and occasion (pickup/delivery/dine-in)

Brand Variations

• Pizza Hut: Separate menu by occasion (delivery vs carryout vs dine-in)
• Taco Bell: Single menu, occasion affects availability of specific items
• KFC: Regional menu variations by franchise group
• Habit Burger: Relatively uniform menu

Key Telemetry

• service:store-menu-dgs @graphql.operationName:* - Menu operations
• @organization - Brand/market filter
• @store.number - Store identifier

Primary Service: go-cart-dgs Orchestrated calls to: promotions-dgs, tax-dgs, delivery-dgs, loyalty-dgs

Cart building is the most complex phase. Each cart modification triggers a cascade of calls to calculate promotions, taxes, delivery options, and loyalty rewards.

Cart Operations (by volume)

1. addLineItemsToCart - Add products to cart
2. localizeCart - Set store/location context
3. updateLineItemsInCart - Modify quantities/options
4. removeLineItemsFromCart - Remove items
5. applyPromoCodeToCart - Apply promo codes
6. applyOfferToCart - Apply loyalty offers
7. updateCartPayments - Set payment method

Promotion Calculation

• promotions-dgs runs calculatePromotionsForCart on every cart change (~104K/hr)
• Automatic promotions applied without customer action
• Promo codes validated against store groups and time windows
• Dual database: promotions-dgs queries both promotions DB (curie) and commercepromos DB (turing)

Tax Calculation

• tax-dgs receives calculateCartTax mutation from cart (~285K/hr)
• Delegates to commercetaxservice via platform-router-internal
• Returns tax breakdown: Sales Tax, Delivery Fee Tax, etc.
• Needs store location from store-menu-dgs for tax rate lookup

Delivery Routing (if delivery order)

• delivery-dgs checks storeDeliveryProviders for the store
• Gets delivery estimate (ETA, cost) from DoorDash API
• Most errors are "Dropoff address not within service area" (user_error)

Loyalty Integration (if loyalty member)

• loyalty-dgs checks loyalty status and available rewards
• Pizza Hut: Calls Punchh API (authapi.punchh.com)
• KFC/Taco Bell: Calls Cheetah Digital (cheetahedp.com)
• Also calls order-dgs, customer-dgs, store-menu-dgs for cross-service data

Brand Variations

Service: payment-dgs

Customer submits payment for authorization (not capture - that happens after order confirmation).

Payment Flow

1. beginPaymentSession - Initialize payment session
2. createPaymentToken - Tokenize card (if new card)
3. authorizePayment - Send auth to processor

Payment Processors

Key Telemetry

• @event.action:payments_post_auth - Authorization attempts
• @metadata.status:APPROVED|DECLINED - Auth result
• @metadata.tender_product_type - Visa, Mastercard, Apple Pay, etc.
• @metadata.bank_card_type - Card type
• @error.generic_error.error_code - Decline reason code

Common Error Patterns

• Decline spikes by card type - Usually processor-specific, check Fiserv/Cybersource status
• beginPaymentSession anomaly - May indicate fraud/bot activity (PH US "worry" threshold: 50K denies/day)
• Gift card declines - Check Fiserv gift card endpoints specifically

Services: order-dgs -> workflowservice -> payment-workflowservice

Order Lifecycle (Temporal Workflow)

SUBMITTED -> CONFIRMED -> PREPARING -> READY -> COMPLETED
                |
                v
            REJECTED (by brand/POS)

1. order-dgs receives submitOrder mutation
2. workflowservice starts Temporal workflow for order lifecycle
3. Order transmitted to brand POS/middleware:

• TB: via PARM (parm-next-gen) -> Poseidon POS
• PH: via phc-order-middleware -> brand POS
• KFC: via kfc-digital-order-services -> brand POS

1. Brand confirms or rejects the order
2. On confirmation: payment-workflowservice captures payment
3. Order status updates flow back through workflowservice

Order Transmission by Brand

Key Telemetry

• service:order-dgs @event.action:* - Order operations
• service:workflowservice @evt.name:* - Workflow state transitions
• service:workflowservice @evt.name:reject_order - Order rejections (brand-initiated)
• @metadata.order_id - Order UUID
• @store.number - Store number
• @organization - Brand/market

Common Failure Patterns

• Order rejected by brand - Menu mismatch, POS offline, start-of-day not run
• Temporal workflow failure - "unable to execute order workflow" = Temporal namespace rate limiting
• Payment capture failure - Auth succeeded but capture failed (check payment-workflowservice)
• Submission not found - "submission not found - null received" = potential duplicate orders

Event Routing (Switchboard)

Every significant action publishes events via switchboard-dgs:

• Order events -> brand webhooks, analytics, notifications
• Customer events -> CRM, loyalty providers
• Payment events -> reconciliation, reporting

Monitoring Coverage

The customer order flow is covered by these IM-notified monitor categories:

• Synthetic health checks: payment-dgs, tax-dgs, delivery-dgs, idpservice
• Throughput anomaly: All critical path services
• Error rate: Cart tax errors, delivery failures, order rejections
• Latency anomaly: Promotions, tax from cart
• Order lifecycle: Confirmation drops, rejection spikes, Temporal failures
• Payment: Authorization anomalies, payment session fraud detection
• Infrastructure: RDS connections, Couchbase, firewall CPU

Investigation Starting Points

When an incident affects the ordering flow:

1. Which phase is impacted? Check service-level errors/latency
2. Which brand/org? Filter by @organization
3. Which stores? Filter by @store.number
4. Upstream or downstream? Check dependencies in service profiles
5. Vendor issue? Check Fiserv/Cybersource/DoorDash/Punchh/Cheetah status pages