web-shop-basket

The client route tree is intentionally small: AppRoutes picks a wrapper, BasketPage decides whether to show the journey or a skip spinner, and BasketJourney hands off to either EmptyBasket or BasketContainer. The real complexity starts after that handoff because package rows, banners, add-ons, modals, and totals all branch from transformed basket payloads and flags.

Development and production servers share the same core responsibilities: load config, enable feature flags, optionally mount mocks, rewrite or redirect auth endpoints, proxy basket traffic, and finally serve the SPA shell. Development adds Vite middleware and a local HTTPS server; production switches to vfukServer, static asset serving, and Datadog tracing.

The basket depends on the basket API, content-service, LaunchDarkly, IDM login, DXL proxying, analytics, and Azure pipeline or release infrastructure. Those systems are not just delivery details: their payloads and availability decide which routes, banners, CTAs, and deep child components the customer actually sees.

The basket codebase still ships as one main SPA, but federation gives the platform smaller runtime contracts it can load independently: a full journey shell, a non-empty basket container, and a shared basket service. Those surfaces export host-friendly entry points such as mount(), unmount(), update(), and validateProps() instead of only exporting React components for local imports.

Shared runtime dependencies live under src/client/federated/shared/import-map.json. The client bootstrap sets sharedDependencyBaseUrl to /basket/federated/shared or to the CDN equivalent, and window.__dynamicImportPreload__ prefixes runtime preloads with /basket. That is why hosts can share React instead of each federated entry bundling its own copy.

1. express.json(), express.urlencoded(), and cookieParser() normalize request input.
2. initFeatureFlagService() and featureFlaggingMiddleware() evaluate LaunchDarkly-backed flags and expose GET /basket/flags.
3. mockingMiddleware() mounts local mock routes for basket, validation, content, portability, and auth session traffic when enabled.
4. cleanRouteMiddleware() and contentAPITransformer() rewrite route and content-service requests into the platform shape.
5. authRedirectMiddleware(), loginRedirect(), and idmMiddleware() protect basket routes and map login/session endpoints.
6. dxlProxyMiddleware() forwards basket API traffic through the configured encrypted gateway.
7. Index routing and static asset serving finally return the SPA shell and federated bundles.

mocking.middleware.ts mounts a dedicated local API surface under /basket, including /basket/mockData, /basket/auth/session, /basket/api/content/asset, /basket/api/content-service/v2/content, and a range of basket validation and mutation endpoints. That is why mock mode can drive meaningful local journeys instead of just returning static HTML.

getGlobalConfig() loads environment variables, parses FEATURE_FLAGS into typed config objects, and decides which middleware and proxies are enabled. pathPrefix is consistently /basket, and route prefixes come from src/common/config/route.ts.

1. cleanRouteMiddleware() strips the /digital/vX prefix and normalizes basket paths.
2. contentAPITransformer() rewrites specific content-service and footer or meganav requests into the payload shape the downstream services expect.
3. authRedirectMiddleware(), loginRedirect(), and idmMiddleware() can intercept auth-scoped routes before any business proxy is reached.
4. Basket API requests then flow through dxlProxyMiddleware(), while image and environment-wide requests use the dedicated image or environment proxies instead.
5. Local assets, /basket/federated bundles, and the import-map JSON never leave the basket server at all.

useStore() returns two singletons: basketStore and uiStore. Most components import the hook directly instead of receiving state through props or context. That keeps shared state simple, but it also means render ownership and state ownership are tightly coupled.

basket.state.ts holds the transformed basket, computed route helpers such as isSeamlessMigrationJourney, the parsed queryMap, page content, validation response, flags, and convenience getters like isEmpty, hasSmartWatch, and rpiContent.

ui.state.ts owns modal visibility, notifications, CTA disablement, border styling, and computed pageError. This is why top-level shells such as BasketPage and BasketJourney can change behavior without re-plumbing props through intermediate components.

basket.actions.ts is the real data loader. loadBasketContent() fetches /basket/flags through getFlagData(), then loads transformed content-service data through contentService.getAssetModel(). Only after that does the client load or create the basket and transform it into the model consumed by the UI.

basketService emits basket events through eventService, and useBasketSummary() publishes a summary to window.VFUK.basketData. That gives external hosts and federated consumers a stable way to observe basket state without owning the whole MobX store.

Note: The basket API does not support native PUT/DELETE from the browser. Mutations use POST with an X-HTTP-Method-Override header, and deletions use the Axios delete() method.

1. Call validateCheckout(basketId)

   POSTs to /packages/discounts/validation. Sets isValidating: true in store while in-flight.

2. No package validations returned + not removing packages

   Hides the discount modal (setShowPreCheckoutDiscountModal(false)) and redirects to basket.checkoutUrl or falls back to /secure-checkout.

3. Package validations present (status ADD / REMOVE / UPDATE)

   Sets validationResponse in state, then shows the pre-checkout discount modal (setShowPreCheckoutDiscountModal(true)). User reviews changes and confirms before redirect continues.

4. Error path

   Calls handleSeamlessMigrationErrors(error) — redirects if in the migration journey. Otherwise updates uiStore status to 'basketIsInvalid' and fires an analytics inline-component-error event.

• Credit vet declined (creditVetId === 'D') — redirects to /en/checkout-credit-fail.html, no validation call made.
• Too many packages — sets notification 'tooManyPackages', blocks checkout.
• Unacceptable recurring charge — sets notification 'unacceptableRecurringCost', blocks checkout.
• Abandoned basket — syncs basketId cookie to match server state before proceeding.

1. Early exit to NO_CREDIT_CHECK

   Missing scenario data or a missing monthly-spend limit immediately suppresses the configurator. BasketJourney never renders the tray in this state.

2. Credit risk with tenure already maxed out

   If there is a minimum-upfront rule, the selected tenure is already 36, the monthly limit is still exceeded, and the backend is no longer recommending a higher tenure, the helper classifies the case as CREDIT_RISK_WITH_TENURE_AT_MAX.

3. Credit risk with a usable tenure increase

   If there is a minimum-upfront rule and the basket can move to the suggested tenure while the monthly limit is still exceeded, the helper returns CREDIT_RISK_WITH_TENURE.

4. Credit risk upfront only

   If the previous two branches fail but the basket still has a credit-risk upfront rule, the helper falls back to CREDIT_RISK_UPFRONT_ONLY.

5. Affordability only

   If there is no upfront rule but the monthly limit is exceeded and the tenure can be increased, the helper returns LESS_AFFORDABILITY.

1. Cookie override

   If a flag-named cookie exists (set via MockSelector or manually), its value wins unconditionally.

2. URL query parameter

   ?flagName=true is checked next — useful for shareable test URLs without touching cookies.

3. LaunchDarkly payload

   The serialised flag array from /basket/flags is the production source of truth.

4. Default

   Hardcoded fallback values in FEATURE_FLAGS_CONSTS — always false unless explicitly defaulted otherwise.

1. Server boot decides whether the middleware exists

   mockingMiddleware() only mounts when config.middleware.mockingMiddlewareEnabled is true.

2. The browser chooses a scenario

   MockSelector requests /basket/mockData, renders grouped options, then stores the chosen values in cookies.

3. Handlers read cookies, not query strings

   Each mock handler calls isMockingEnabled(req), which is effectively a basketMock cookie check. The chosen cookie value determines the fixture path.

4. Specific handlers serve basket, content, validation, and mutation flows

   Basket GET, validation POST, content assets, auth session, portability, and generic basket mutations each have a dedicated handler path under the mock middleware.

useBasketSummary() publishes a basket summary to window.VFUK.basketData after every basket update. External hosts and other federated modules can observe this without owning the MobX store. basketService also emits basket-change events through eventService for the same reason.

handleSeamlessMigrationErrors(error) is called before standard error handling in validation and mutation actions. If the current journey is a seamless migration route, it redirects to a journey-specific error URL instead of showing an inline notification. This prevents the generic error banner from appearing in a flow that has its own error pages.

1. The preprocessor turns feature files into runnable specs

   cypress.config.ts wires the Cucumber preprocessor together with the esbuild bundler and fail-fast plugin.

2. Global support code bootstraps the browser

   support/e2e.ts loads custom commands, accessibility helpers, Percy CSS fixes, and uncaught-exception suppression before the first step runs.

3. Steps call shared commands instead of duplicating raw intercepts

   Step files use commands like setScenarioMocks(), loadPage(), and analytics helpers so each feature focuses on business behavior instead of setup plumbing.

4. The app still runs at the real route

   Most scenarios visit http://localhost:8000/basket and let the client runtime execute normally, with network responses controlled by intercepts or shared fixtures.

Production tracing starts in src/server/production/tracer.ts. Server logging uses the shared Node logger, and health checks are mounted through the platform health-check package during server bootstrap. In the client, analytics flow through AnalyticsUtil rather than being emitted ad hoc from random components.

BasketJourney.tsx — the top-level journey shell. Owns the conditional rendering tree for every major journey branch.

• Reads basketStore.state and uiStore.state via useStore().
• Mounts BasketCreditCheckConfigurator when ISHARDCREDITCHECKENABLED flag is on and scenario is actionable.
• Mounts EECCModal for energy/environmental switching confirmations.
• Handles ?validate=true query via handleQueryChange().
• Shows PageLoading spinner while isLoading or isValidating is true.
• Falls through to EmptyBasket when basketStore.state.isEmpty.
• Falls through to BasketContainer for the normal journey.

BasketContainer.tsx — wraps the basket body. Handles ?reviewMode (Shadow DOM embed) and ?showModalsOnly branches.

• In reviewMode: renders into a Shadow DOM root via react-shadow, trims promo chrome.
• In showModalsOnly: renders only ModalContainers — used by other flows embedding basket modals.
• Shows LoginBanner for unauthenticated seamless-migration customers (getState().isLoggedIn === false).
• Renders: page title and banners → BasketContents → discounts, totals, RPI → BasketPageButtons.

Renders the list of packages. Reads basket.combiPackages and basket.singlePackages from store.

• Combi packages → BasketCombiPackage (linked handset + watch or HBB + SMOS).
• Single packages → BasketPackage.
• Premium delivery item rendered separately if deliveryType === 'PREMIUM'.
• No direct API calls — all mutations delegated to store actions.

• BasketPackage — single package row. Receives thisPackage prop and index. Triggers onRemovePackage(), renders PackageHeader + RenderPackageBody → PackageItemList.
• BasketCombiPackage — wraps two or more linked packages (e.g. handset + watch). Removal shows the 'removeCombi' modal which deletes both packages atomically via ?deleteLinkedPackages=true.
• Package header shows status: 'present' (normal), 'removing' (optimistic removal in-flight), 'removed' (undo state).
• Undo timer starts after removal — calls onUndoRemovePackage() if user acts before timeout.

Displays SIM card details for a package's services. Source: src/client/components/ area.

• Shows activation method (physical SIM / eSIM) and phone number if available.
• Links to portability info — clicking opens the portability modal.
• Portability PAC/STAC codes displayed when present in bundle.portability.
• Triggers submitPortabilityInfo() / removePortabilityInfo() API calls via store actions.

• Displays device name, storage, colour, and contract term.
• Shows upfront and monthly price. Includes RPI messaging when applicable.
• Trade-in credit shown as a line item — removable with undo support via onRemovePackageTradeIn().
• BYOD (Bring Your Own Device) handled separately: addByodProduct / removeByodProduct endpoints.
• Contract configurator link appears when tenure options are available via hardwareConfigurator ranges.

• Shows plan name, data allowance, contract length, and monthly cost.
• Bundle switch link calls switchBundle() → PUT /bundle/{bundleId}.
• RPI pricing message rendered from basketStore.state.rpiContent when the flag is active.
• Reads bundle.portability to determine whether portability status is shown here or in SimPanel.

• Renders optional services: insurance, roaming add-ons, handset protection, etc.
• Each service has an individual remove action (onRemoveAddOn()) with undo support.
• Undo calls onUndoRemoveAddOn() → re-adds via addProduct endpoint with original discounts preserved.
• Discount lines shown per service where applicable.
• Multi-line insurance removal tracked in manuallyRemovedMultiLineInsuranceId state to prevent re-offering.

• Renders accessory hardware items (cases, cables, etc.) separately from the main device.
• Individual removal supported. If all accessories removed, package-level removal is triggered.
• Shares the same BasketHardware sub-components for price display.

• Go to Checkout — calls basketStore.actions.handleCheckout() → validateBasket() → redirect.
• Continue Shopping — disabled state controlled by uiStore.state.isContinueShoppingDisabled.
• Empty Basket — calls handleEmptyBasket(), fires analytics, shows confirmation modal first.
• All three buttons read disabled state from uiStore.state.disableActions during any async operation.

• Reads uiStore.state.notification (key) and uiStore.state.pageError (formatted string).
• Displayed at the top of the basket — scrolls into view automatically on error.
• Fires inlineComponentError analytics event when an error is shown.
• Dismissible via a close link which calls uiStore.actions.updateStatus('clear', null).