Table of Contents

Sanity Figma: to be filled by design team

WL Figma: https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/SjrTCnkEyeTsC3NNQRsno4/Burger-King?node-id=37068-15787&t=fTr0rg2b61XwxMYo-0 (temporary branch)

Context

To comply with the government rule requiring bag fee tax information, we need to modify our partners' services to retrieve this data from Sanity and forward it appropriately. We’ll need to show this information in the following applications: POS, DMP, Admin App and Whitelabel App.

Open Decisions

Main objective

• The idea is to create a new document in Sanity to get the Bag Fee tax value (see https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4660560004#Sanity-proposals below for more details) and service mode that will consider this tax

• Get the data from Sanity and adjust the desired flow to:

  • Show Bag Fee value (POS, DMP, Admin app, Admin tools and Whitelabel)

  • Total cart price updated considering the Bag Fee value (that cannot have any discounted value)

• Reuse cart.fees interface in Backend because all the flow is already working with this (saving the value in DynamoDB, show information in Whitelabel App through getOrder)

  • We don’t want the front end to be the source of truth for the bag fee value, and following the WL pattern that we have today, the backend (getting from Sanity there) should return the value, and the front end will be responsible for the presentation layer

# Option 1 - Add logic in partners service to persist bag fee value

Why this can be an option:

• We think that this can be more simple, as we don’t need to change fulfillment/packages and then pass down what’s necessary to partners-service

• Partners service will write to dynamo and then persist the value that will be get from getOrder query

  • We can access Sanity data from there

• This flow and solution is the same for Delivery/Restaurant mode (pickup, etc.). Both will reach partners-service at the end. We also validate in a PoC both graphql and gateway flows

Consequences

Partners API already has this structure mapped/working (Validated in PoC)

Doesn’t require the creation of new queries in front end and has no impact in WL interfaces

Little impact on the tools plataform (POS, DMP and Admin App)

For now, the recovery of the Sanity information will only be developed for partners service flow. As we don’t know how the other services will use this information we are not making this now.

# Option 2 - Add logic in fulfillment

This solution is almost equal to # Option 1. The difference here is:

• We’ll need to access Sanity and get the Bag Fee value in fulfillment service (both in packages/intl-fullfiment and in Intl-fullfilmenent-service)

• We pass the bag fee value into the cart.fees structure to be calculated in partners-service (for the total cart price) adding the value in fulfilment priceOrder() if we get some value from Sanity

Consequences

Fulfillment connected with the solution from Sanity and already passing the value for other POSs/vendors

Doesn’t require the creation of new queries in front end and has no impact in WL interfaces

Little impact on the tools plataform (POS, DMP and Admin App)

The same solution needs to be done in packages/fulfillment and Intl-fulfillment-service

Disregarded alternatives

Create a new property to save bag fee value

We can add a new property in cart structure to save the bag fee value that will come from Sanity. To be able to do that we’ll need to adjust all the flow where this props needs to be.

Consequences

Not scalable and not prepared to save other values

A prop that will only be used for partners for now.

Big impact. Adjust all necessary repos and interfaces (fulfillment, graphql/packages, WL interfaces, etc.)

Assumptions

This solution is intended to be made only in partners service for now. Why?

• We cannot ensure this won't impact non partners POSs (eg. Oheics, Sicom, ...) since we lack the environment and know-how to test them

• Why change the other POSs code to add something that we don’t know will be necessary?

• If we want to at least pass the value for the other POSs, we’ll need to choose # Option 2 (making the solution in fulfillment). If some POSs need a bag fee, then the POSs will need to be adjusted

Detailed changes by project

This section is not required for reading. If you want more details on the impacts/changes in each project/repo feel free to read

 Click here to expand...

Intl-packages and Intl-sanity

We need to adjust this to get the necessary information from Sanity that will be used later on partners-service.

#Option 1 - Create a new service class in sanity packages to use in partners-service

• Create a new folder in intl-packages/packages/sanity/src that will be responsible to get the new bag fee information from sanity

• Create a new class that will be used to inject the information from Sanity in other necessary repos (like the partners-service

  • We can take a look in intl-packages/packages/sanity/src/loyalty/index.ts to know how to implement this

#Option 2 - Not touch in Sanity packages and develop the sanity part locally in partners-service repo OR fulfillment

• Use the Sanity client to get the necessary document values directly at the chosen repository

Intl-partners-service (if #Option 1 is chosen)

• Adjust intl-partners-service/src/modules/orders/orders.service.ts

  • Inject the new Sanity instance (developed above in Sanity service solution) to be able to get the bag fee value

  • Adjust price() method to:

    • Add a new property for bagFee value or reuse the cart.fees property (see more details below)

      

• As this interface is already prepare to deal with bag fee type we just need to assign the bag fee value from Sanity if exists

  

• Interfaces affected:

  • For now, none

Intl-fulfillment-service and Intl-packages/Intl-fulfillment (if #Option 2 is chosen)

• Adjust priceOrder to:

  • Get values from Sanity

  • Add the values ins cart.fees structure

Intl-whitelabel-app

Sequence diagram demonstrating WL communication

Interfaces impact

None. The fees structure already exists in WL App. This value comes from Server Order details (getOrder) at the root of the cart object (cart.fees)

Affected screens

The requirements:

• Show the new bag fee information in:

  • Checkout page

  • Confirmation delivery page and delivery track details modal

  • Receipt page

• Include bag Fee to be considered in Loyalty Points Calculation if checked on Sanity

The following screens are already showing information about these fees if received from backend. We’ll only need to adjust some visual aspects to match Figma proposal.

• Receipt details (if enable-discounts-on-order-receipt flag is ON)

  

• Your cart subtotal section (the fees values will be below subtotal value)

  

• Delivery details

Intl-expeditor-tablet (DMP Frontend)

• Adjust formatRbiFees to include bag fee information

• Add bag fee in fees.dto

• Adjust intl-expeditor-tablet to show bag fee in front-end as well

Admin App

• Backend

  • Adjust cart interface to get fees structure

• Frontend

  • Adjust fechOrder to have fees

  • Adjust tax-fees-and-totals comp to show bag fee in the list of items

Intl-partners-api

• No changes needed. Already prepared

Sanity proposals

Document hierarchy level

We can create a new document inside the “Marketing Content” → “Features” location named for example as “Feature Bag Fee” (this is an example. We can use any desired name for the feature doc).

Following the application design this new file will be inside schemas/features/documents folder.

Form structure

Our document only needs to have:

• Bag fee value configuration for Restaurant mode and Delivery mode. Options that can have bag fee value:

  • Delivery

  • Pick up

  • Drive-thru

  • Curbside

• The user needs to have the ability to configure which service mode option the tax will be enabled (to turn ON/OFF)

  • Fields where the user can put the desired value for each service mode (if enabled)

Technically speaking (short points)

We’ll respect the architecture design that we already have on the application, meaning:

• Documents should be used for new feature pages

• Separated object files should be created to be used as type reference (the nested items showed below on the proposals)

UX proposal

PS: for all proposals, the labels and texts can be changed. The screenshots are here to demonstrate what we can do in Sanity. I’ve added only two service modes in the screenshots for demonstration purposes only (we’ll have more, at least four service modes).

The current screenshots don’t have the field for delivery. The idea here is to add insights for design team to work on. This is not the final result yet as the design is not finished yet.

Insights for design team

# Option 1 - Nested service mode block

 Click here to expand...

• For this options all service modes will be inside the “Service mode” section in the document (as children)

# Option 2 - Same page level isolated blocks

 Click here to expand...

• We can also put the service modes directly on the page without the main section agrouping all service modes as showed in # Option 1

# Option 3 - Only one nested level

 Click here to expand...

• In this option, we’ll not have the second nested level to group each service mode. The toggles and fields will be decoupled inside the main service mode section

# Option 4 - Choose the desired UI based on the other options but migrate the solution to the “Fee Config” document (CHOSEN ONE)

After discussing the options internally, we decided to reuse them to also show and configure the Bag Fee information. The idea is to condition the "fee configuration" document to show the Bag Fee form if the "Fee type" field is selected with the "Bag Fee" value. The design team is working on the proposal.

PS: We’ll add the design here when it’s available. We can also take a look at the other documentation to understand it better.

Pros and Cons

About the form validation

We can add some validations here, for example:

• All value fields can be read-only or disabled until the user enables the respective field

  • If the user does not fill out the field, we’ll show an error saying that the field is now required as the user has enabled the respective service mode. This will block the page from being published

  • We can also add validations to ensure that the user will fill out the respective field if the service mode is enabled without the read-only or disabled UI

Scalability and other options of solution

The main idea here is not to add additional complexity if it isn't necessary! Let’s think: “What do we need to configure the Bag Fee?”. Besides that, I’ll add here some insights to improve the scalability of the document if we need to have more complex configurations or other fees.

If we need to configure other fees value

 Click here to expand...

• Use fieldset/collapses structures to isolate each fee form

• We can have multiple fees fieldset groups (bag fee, service fee, etc..)

• We can have different form setups in each fieldset as desired

If we need to configure fees by restaurant list