Tech discovery - Free refill QR code

Owned by Raphael Ferreira Gomes
Last updated: Dec 21, 2023
8 min read

During the Tech Discovery of the feature Free Refill Drinks (QR code), we identified two possible approaches of solution.

The first one is based on partners described below under Approach 1. This solution intends to generate the QR code based on a encoded hash that the POS Vender (Winrest) will respond once the order is sent to the kitchen (Commit Order and Commit Order Callback). With this, we just need to change backend APIs to store this info in the database (DynamoDB) and then enhance WL to read this info.

The second approach is a standalone solution and is described below in Approach 2 section. This solution relies on a enhancement of the internal configuration of the items and stores, so that they will have an identifier to mark them as eligible to generate the hash/refill drink QR code or not. Said that, WL must read this info from the Order items/store and apply the business logic.

Approach 1 : Refill drinks code generated based on partners

Sequence Diagram

https://lucid.app/lucidchart/2e8d5dc1-74c3-45f2-ad7d-45ae309a89ae/edit?viewport_loc=-595%2C627%2C3357%2C1850%2C0_0&invitationId=inv_a0954c87-16c5-4b55-b3ef-224665d8ce2e

Reference: https://euc1-dev-bk-partners-api.rbictg.com/docs/market/#tag/OrderWebhook/operation/webhookOrdersCommit

  • Commit Order (sync)

 

  • Commit Order Callback (async)

 

Considering a new optional string field (or reuse existing externalReferenceId from commit order flows) to fit the refillDrinkHash (Vendor machine refill drinks) in the response.

To check with POS Vender if Fire Order. Paulo is checking..

Datadog example

CloudWatch Log example

Approach 2 : Refill drinks code generated without partners (standalone)

Sequence diagrams proposals are shown below. Main difference consists on which moment refill drinks are retrieved to be evaluated. Either on the store selection and item selection, or just when the customer is about to place the order.

Sequence diagram 2.1 → To be validated in PoC ( @Augusto de Souza, Jonatan (Deactivated) @Goncalves, Felipe )

Sequence Diagram 2.2 (to be validated in PoC) → @Goncalves, Felipe @Augusto de Souza, Jonatan (Deactivated)

Generate Hash Code

  • MD5 - WinRest Logic to calculate hash:

  • DynamoDB secrets table: rbi-account-secrets

Sanity

 

  • Marketing Content / Features/ Feature QR Code Refill Drinks / List of items

    • TBD

  • Marketing Content / Features/ Feature QR Code Refill Drinks / List of stores

    •  

Figma (UX)

https://www.figma.com/file/sfH3mHXoEUfHbm5qMul0Vn/branch/vHkAnCCKjzCGg7ibeurVLW/Popeyes?type=design&node-id=4109-147585&mode=design&t=qfsQcFhawcNhDpIO-0

https://www.figma.com/file/sfH3mHXoEUfHbm5qMul0Vn/branch/vHkAnCCKjzCGg7ibeurVLW/Popeyes?type=design&node-id=6154-20378&mode=design&t=rI0nV0lqvOB2IWeF-0

 

FAQ

  • What’s the API that whitelabel needs to call to receive as response the hash to be converted into QR code? What is the response field? Any example?

    • In approach 1, it’s commit order and commit order callback. In approach 2, no external API is needed.

    • Hash: 2bb4193529026315ce6ca36dbc6831ef

  • What’s the content of the hash?

    • This field is the result of several fields encrypted with a password provided by the vending machine team: Example:

      • Store ID: 103
        Transaction ID: 84970387 → is it posOrderId?
        Date and time stamp: 20211031013000

  • Can the hash content be generated inside RBI app?

    • Yes, it can. But we need the the secret to generate the encoded hash that the vending machine will decode. Besides, we need to configure all items and all stores that grants the right of refill drinks. All the logic would be internal.

  • What’s the handle component (sticker) of the bottom?

    • We checked existing storybook component, but no one looks good for it

    • Proposal: create a new one:

    • Example :

  • What are the icons for 'refill drink' and qr-code ?

  • What are the impacts on Recent Order page?

    • This page can be reached via several flows. Left menu, Bottom menu (icons), deeplink account/orders), etc. The point is that, while refill drink is available, this screen should be incremented with a new component in the header. Additionally, a new modal should be created to display the QR code:

  • How long should the QR code be visible?

    • It should be configurable in Sanity. @Hainzenreder, Diego could you please validate?

  • For which service modes is it applicable?

    • Obs: there could be the possibility/need to have the service modes configurable in Sanity as well (ex: Curbside today is not included but could be done in the future) → to analyze effort

  • What’s the logic to show the QR codes?

    • Bottom sticker QR code: During the modal transitions, while last ‘refill drink’ recent order time + bottom sticker duration time > current time.

    • Recent Order QR code: In recent order page rendering, while last ‘refill drink’recent order time + recent order duration time > current time

    • Obs: Refill drink order = Last order with POS hash. To be stored locally. Not in DB.

  • Where will be defined the text messages?

    • Text message in lokalise:

 

  • How to translate hash into visual QR code?

  • If a customer makes an order from one platform, will it be available in another platform? Eg.1: Customer orders in Web and signs in Android. E.g2. Customer orders in Android and signs in IOS.

    • For v1, no. As improvement, we can persist the hash in database and implement an API to make a query in order to get the last order with hash and still valid in terms of duration.

  • For which platforms will it be available?

    • IOS and Android. Web is out-of-scope.

  • Depending on the service mode, customer can schedule when to take the order. Should the QR code be displayed anyway?

    • Yes. If it expires in bottom sticker, customer can still go to recent order page

  • Do we need to validate if the Order is still active (Not refunded)? Reason - avoid refill drinks for customers with cancelled order.

    • We need to ensure that the order status is either INSERT_SUCCESSFUL or UPDATE_SUCCESSFUL. See the order flow below

Checking if the edit time modification / cancellation was indeed implemented : thread

Epic Breakdown

Approach 1: Based on partners → 22 + 10 + 37 + 13 + 20 + 16 + 3 + 34 = 155

  • Backend Services - (22)

    • Packages (Interface) - 2

      • Change the IPartnerOrder interface to add a new refillDrink field. (Interface).

    • Commit Order and commit order callback - 20

      • intl-partner-api - Callback- (5)

        • Add new field "refillDrink" in DynamoDB update (Reference Code) (3)

        • Add new field “hash” as optional in DTO. (2)

      • intl-partners-service - (5)

        • Add new field "refillDrink" in DynamoDB update (Reference Code) (3)

        • Add new field “refillDrink” in Webhook Order interface (Interface) (2)

      • intl-fulfillment-service - (3)

      • intl-whitelabel-graphql - (5)

  • Front-end

    • Place Secure Order

      • Get Order - 10

        • graphql - get order with refill drink hash - 5

        • database get order with refill drink hash - 5

      • Hook Refill Drinks - 37

        • Validate Get Order - check Refill Drinks hash - 5

        • Validate Service Mode (Sanity) - 8

        • Trigger bottom sticker - 8

        • New modal of QR code - 8

        • Convert hash to QR code - 8

    • Recent Order Page - 13

      • Hook Refill Drinks banner

        • Validate Orders

          • Read bottom sticker order - 3

          • Read Sanity Config (duration) - 5

          • Apply logic to show banner - 5

    • Home Page - 20

      • Check if there’s QR code order in cache - 5

      • Read Sanity config (sticker duration) - 5

        • Apply logic to show bottom sticker of QR code - 5

        • Add/Remove QR code order in cache - 5

  • Sanity - 16

    • New Feature Refill Drinks - 8

      • Duration of bottom sticker - refill drinks

      • Duration of recent order - refill drinks

    • Configuration of service modes - 8

  • Feature Flag - 3

    • New feature flag for front-end

    • New feature flag for back-end

  • Testing - 34

    • Testing Plan

    • Dev - using mocks

    • QA, STG, PROD - using integration with Winrest

    • Validations in dynamodb

    • Validations of durations of QR code

      • bottom sticker

      • recent order sticker

    • Validation of the last order QR code

    • Validations using native devices

      • responsiveness

      • QR code reading

 

Approach 2: (Standalone) without partners → 10 + 28 +21+8+ 65 + 24 + 13 +20 + 16 +3 +34 = 242

  • Implementation of refillDrink in Sanity - 10

    • New Refill Drink feature section to define:

      • List of stores eligible for refillDrink (5)

      • List of items eligible for refillDrink (5)

  • Configuration of refillDrink in Sanity - 28

    • List of stores eligible for refillDrink - ~40 stores (8)

    • List of items eligible for refillDrink - thousands ( 20 ) ?

  • Synchronization of refillDrink configuration (PortalOps) - 21 ?

  • Configuration of secrets in dynamodb - 8

  • Intl-whitelabel-App

    • New hook to generate the refillDrinkHash ( 65 )

      • validate getOrder response refillDrink fields - 13

        • Retrieve:

          • storeId,

          • transactionId (posOrderId?),

          • order timestamp

      • Get secrets from the database - 13

      • Read eligible drinks and stores from Sanity → 26

        • validate if the storeId is eligible for refillDrink (8)

        • scan menu items ( 13 )

          • Check if any menu item is eligible for refillDrink ( 5 )

      • Apply encryption with the secret key (13 )

 

  • Place Secure Order - 24

    • Get Order - 10

      • graphql - get order with refill drink hash - 5

      • database get order with refill drink hash - 5

    • Hook Refill Drinks

      • Validate Get Order - check Refill Drinks hash - 5

      • Validate Service Mode (Sanity) - 8

      • Trigger bottom sticker - 8

      • New modal of QR code - 8

      • Convert hash to QR code - 8

  • Recent Order Page - 13

    • Hook Refill Drinks banner

      • Validate Orders

        • Read bottom sticker order - 3

        • Read Sanity Config (duration) - 5

        • Apply logic to show banner - 5

  • Home Page - 20

    • Check if there’s QR code order in cache - 5

    • Read Sanity config (sticker duration) - 5

      • Apply logic to show bottom sticker of QR code - 5

      • Add/Remove QR code order in cache - 5

  • Sanity - 16

    • New Feature Refill Drinks - 8

      • Duration of bottom sticker - refill drinks

      • Duration of recent order - refill drinks

    • Configuration of service modes - 8

  • Feature Flag - 3

    • New feature flag for front-end

    • New feature flag for back-end

  • Testing - 34

    • Testing Plan

    • Dev - using mocks

    • QA, STG, PROD - using integration with Winrest

    • Validations in dynamodb

    • Validations of durations of QR code

      • bottom sticker

      • recent order sticker

    • Validation of the last order QR code

    • Validations using native devices

      • responsiveness

      • QR code reading