web-shop-checkout runtime guide

Overview

web-shop-checkout is Vodafone's route-driven checkout and order-completion app for online shopping journeys outside VOXI. The repo combines a React + MobX client, a shared route/config layer, and Express/Vite server runtimes that proxy backend APIs, auth, flags, and AIM mocks.

Tech stack

The app is a React 18 checkout running on a MobX singleton-store model, fronted by React Router and backed by Express/Vite middleware, Contentful, LaunchDarkly, Adobe Target, and AIM.

Getting started

The local developer path in the README is: install dependencies, copy env templates, generate the local certificate, run the HTTPS server, add ?debug, and then set or generate a basketId.

Runtime architecture

There are three runtime layers to keep in mind: client boot and route ownership, MobX-driven journey/panel orchestration, and the server middleware stack that injects auth, flags, proxies, and mocks.

Route and runtime map

The graph below follows the real runtime hand-off from browser boot into the route tree, AppInit, checkout/panel orchestration, order submission, processing, and final outcome pages.

Render breakdown

This is the runtime ownership map from route shells down into meaningful children. The groups are ordered from shared owners to deep panel families and standalone routes.

State management

The app uses MobX singleton stores rather than React context for shared state. The strictest rules live in CheckoutStore, which calls configure({ enforceActions: "always" }), while other stores derive branch conditions or expose domain-specific data slices.

Core request lifecycle

A successful checkout submission is not a single request. The normal path is checkout bootstrap, basket hydration, panel-specific PUT/POST submissions, optional payment/3DS hand-off, order-state polling, and then a refreshed order-complete render.

Server and runtime layer

The repo ships two server entrypoints that share most of the same middleware chain: a production Express runtime and a Vite dev server. Both are responsible for route prefixing, auth/session middleware, flags, proxying, and AIM support.

Content, config, and flags

Content and toggles arrive through multiple channels. Contentful-backed content comes through ContentService and is consumed by both newer stores and a few tactical legacy calls. Feature flags arrive server-side through LaunchDarkly and client-side through Adobe Target on window.vfukTnt.

Component inventory

The inventory below is broad on purpose: it covers route owners, panel orchestration, key panels, stores, and service/runtime modules that materially affect behavior.

File structure and aliases

The repo is split between src/client, src/server, shared route config, worker transforms, Cypress/Jest harnesses, and AIM mock payloads. Path aliases in tsconfig.json are used heavily across the codebase.

Tooling and testing

Most local workflows are script-driven through package.json, with Jest for unit coverage, Cypress for E2E and visual runs, and Sonar/ESLint/TypeScript for quality gates.

Unresolved areas

A few parts of the runtime are intentionally external or only partially visible from this repository. They are worth calling out so new engineers know where code evidence ends.

Federated basket deep dive

The checkout does not render its own order-summary UI. Instead it delegates that work to an independently deployed micro-frontend — the federated basket — loaded at runtime via the Vodafone Federated Module system (@vf/federated-react, @vf/federated-core). This section explains exactly what "federated" means here, how the basket data flows in, and which parts of the checkout it affects.

What is the federated basket?

Vodafone's online properties use a micro-frontend architecture where different squads own different UI surfaces. The basket is maintained by a separate team and deployed independently as a remote bundle. When web-shop-checkout needs to show an order summary (in ReviewYourOrder and on the FakeFederatedBasket dev route), it pulls that remote bundle from a known URL (/basket/federated) and mounts it inside the page. The checkout never contains the basket rendering code; it only acts as a host.

How the bundle is loaded

Data flowing into the federated basket

The basket needs to know what is in the order so it can display a correct summary. The checkout owns that data — it is fetched from the backend and stored in CheckoutStore.basketData. Two mechanisms send that data to the federated component:

What CheckoutStore.basketData contains

basketData is the raw basket payload fetched from GET /api/basket/v2/basket/{basketId} and reshaped by the basket web worker. It is the same data that BasketStore uses to build payment-panel breakdowns and order-complete summaries. Key sections include:

• Products / packages — handset, SIM, broadband, or accessory lines with their individual prices.
• Discounts and promotions — applied offer codes and their monetary effect.
• Delivery charges — shipping cost for the selected delivery method.
• Upfront and recurring totals — the amounts surfaced in the payment panel and in the review summary.
• Trade-in value — deducted from upfront costs when a trade-in is present.

Which checkout sections involve the federated basket

Panel — About You

The first panel in almost every journey. It collects the customer's identity — personal details, customer type, and journey-specific fields — and is the earliest branch point in the checkout. The optimised variant (OptimisedAboutYou) is an Adobe Target experiment with the same backend contract.

API call

What the front-end sends

Required fields to continue

• All fields marked "Always" must be populated and pass JSON Schema validation.
• The backend validates the payload against a schema fetched via GET /checkoutInfo/v2/{checkoutId}/personalDetails/schema during app init.
• The backend response must return a statusInfo.status that is not an error for the panel to transition to summary state.
• Email uniqueness is checked client-side first via POST /authorization/v2/action/doesUsernameExist — a non-unique email blocks submission before the panel PUT is even attempted.

Panel — Affordability

A confirmation-style panel — not an input form. The customer reads an affordability summary table and checks a box to confirm their circumstances have not changed since they first applied. It is used in Bingo (device finance) journeys where a credit decision already exists but a formal affordability affirmation is required before the loan documents can be shown.

API call

What the front-end sends

Required fields to continue

• The only required field is noChangeInCircumstances: true.
• The "Agree & continue" button is disabled until the checkbox is ticked.
• Backend must return a non-error status on the affordabilityDetails object in the checkout response.

Panel — Address Details

Collects up to three years of UK address history. The front-end uses a premises lookup service to let customers find their address by postcode, then records how long they lived at each address and their residential status. A sibling panel — AddressCheck — handles a simpler variation for authenticated users who need to confirm (rather than enter) their address.

API calls

What the front-end sends (personalDetails PUT)

Required fields to continue

• A minimum of three years of continuous address history must be provided. If the current address covers fewer than three years, additional address entries are required.
• Each address entry must have a valid dateMovedIn, postcode, street, and city.
• The primary address must have a residentialStatus.
• Backend validates the full payload and returns errors per-address if any entry is incomplete.
• AddressCheck variant: the customer confirms a pre-populated address from their account; the only additional required field is dateMovedIn for each address entry. The same personalDetails PUT is used.

Panel — Delivery

Lets the customer choose how and where their order is delivered. There are three panel variants covering different product types: standard Delivery for handsets and SIMs, BroadbandDelivery for router/equipment shipping, and RedDelivery for PAYG+ orders that need a combined delivery and billing address step. All three write to the same backend key (deliveryOptions) via the same PUT endpoint.

API calls

What the front-end sends (deliveryOptions PUT)

RedDelivery additional fields

Required fields to continue

• A delivery method must be selected (home delivery or click & collect).
• A valid delivery address must be chosen from the premises lookup results — free-text address entry is not permitted on this panel.
• If PAC/STAC switching restrictions apply (e.g., NI restriction), a modal error is shown and the panel cannot be submitted until the issue is resolved or the modal is dismissed with an alternative action.
• BroadbandDelivery: if the journey is activation-only (no physical router), this requirement is relaxed — the panel submits without address fields.

Panel — Monthly Payment

Collects the customer's Direct Debit bank account details so that recurring monthly charges can be set up. It is a thin shell around ActivePanel (bank details form) and Summary (the completed state). Editing this panel can also re-open the Spend Manager panel when bill-capping state is linked.

API call

What the front-end sends

Required fields to continue

• All five fields above are required.
• Sort code and account number are validated against format rules client-side before submission.
• Backend performs a Modulus check on the sort code / account number combination and will return an error if the bank account is not valid.
• If Spend Manager is also in an active state (e.g., the user navigated back to edit), both panels must be re-submitted before checkout can progress.

Panel — Payment

The upfront / card-payment panel. It handles one-off charges such as a handset upfront cost, a PAYG+ SIM purchase, or a Bingo device deposit. Because this panel touches raw payment-card data it uses a remote payment iframe for PCI compliance — no card numbers are ever handled by the checkout JavaScript directly.

API calls

What the front-end sends

Payment iframe flow

• When a card requiring 3DS or new-card entry is selected, initiateCardPayment is called. The response contains an iframe URL.
• The checkout renders that URL in an <iframe> — the remote page (owned by the payment provider) collects the card number, expiry, and CVV.
• The iframe posts a window.makeGetWebPayment() callback on success, which the checkout intercepts to trigger order submission or 3DS redirect.
• No card data is ever sent through the checkout's own APIs. This is intentional PCI DSS compliance.

Required to continue

• A payment card must be selected (existing saved card or new card entered in the iframe).
• If 3DS authentication is required, the customer is redirected to /secure-checkout/card-authentication and must complete the bank challenge before order submission continues.
• A backend error on paymentDetails.statusInfo will surface an inline panel error and block progression.

Panel — Spend Manager

An optional panel that appears after Monthly Payment for logged-in customers. It lets them set a bill cap per package to protect against unexpected overage charges. Customers can configure caps immediately or defer to later — both choices are valid completions.

API call

What the front-end sends

Required to continue

• The customer must either select a cap level for each package or click "No, maybe later". There is no other blocking requirement.
• Multi-plan journeys render one BillCapSelector row per active package; all rows must have a selection before the continue button enables.

Panel — Your Account (Create Your Account)

Shown for anonymous customers who do not yet have a My Vodafone account. It combines account credentials (email, password, PIN), accessibility preferences, marketing consent, and optional confirmation-letter preferences into a single step. The Preferences panel is a lighter variant for authenticated customers who already have an account but still need to set accessibility and consent preferences.

API calls

What the front-end sends (personalDetails PUT)

What the front-end sends (accessibilityDetails PUT)

Required to continue

• Email must be unique (checked via the doesUsernameExist endpoint before the main submit).
• Password must meet complexity rules (validated client-side via JSON schema from the validation service).
• PIN must be exactly 4 digits.
• Marketing consent fields must be explicitly set (opt-in or opt-out — an unset state is not accepted).
• Both the personalDetails and accessibilityDetails PUTs must succeed before the panel transitions to summary.

Panel — Review Your Order

The final panel before order submission. It hosts the federated basket component (the order summary), surfaces any pending panel errors, and exposes the Terms & Conditions checkbox and the "Place order" button. Clicking "Place order" hands control to OrderSubmissionRedirectService, which navigates to either the processing screen or (if 3DS is required) the card-authentication screen.

API calls

What is checked before "Place order" is enabled

• panelsStore.isReadyForSubmission must be true — every panel ahead of Review Your Order must be in its summary (completed) state.
• The Terms & Conditions checkbox must be ticked.
• The federated basket must have loaded without an error (if it fails, a blocking message is shown).

Post-submission flow

• If no 3DS is needed → navigates to /secure-checkout/processing.
• If 3DS is required → navigates to /secure-checkout/card-authentication, the customer completes the bank challenge, then the window.makeGetWebPayment() callback re-enters the submission flow.
• OrderProcessingService.beginProcessing() polls GET /api/checkoutInfo/v2/{checkoutId}/orderState on the processing screen until a terminal state (accepted / conditional / declined) is reached, then routes to the appropriate /secure-checkout/submitted|conditional|error page.

All API requests

Every HTTP request this service makes to backend systems, organised by domain. The base path for all checkout endpoints is /api/checkoutInfo/v2/{checkoutId}. The {checkoutId} is created on first load and stored in session storage; all subsequent panel submits reference it. All requests go through DataService.request(), which adds AIM tracking keys in development mode.

Checkout lifecycle

Panel data submissions

Utility and lookup endpoints

Basket and content endpoints