Vodafone SIM-Only Storefront

web-shop-simo is the Vodafone UK SIM-only online storefront. It serves consumer and business customers across multiple purchase journeys — acquisition, upgrade, second line, pay-as-you-go migration, tariff migration, and seamless customer transfer.

Tech Stack

Getting Started

Prerequisites

• Node.js 22.22.0 (use nvm or fnm)
• Yarn 1.x
• Access to Vodafone VPN (for environment proxying)

Commands

# Install dependencies
yarn install

# Start dev server (INT1 environment, HTTPS, port 8000)
yarn start

# Alternative environments
yarn start:qc1       # QC1
yarn start:qc2       # QC2
yarn start:prod      # Production simulation
yarn start:prerender # With prerender enabled

# Testing
yarn test                   # Run all unit tests
yarn test MyComponent.test  # Run specific test
yarn test:coverage          # Full coverage report

# Linting
yarn lint        # ESLint + Stylelint
yarn lint:js     # ESLint only
yarn lint:styles # Stylelint only

# Build
yarn build:federated  # Micro-frontend SystemJS bundle

# QA pipeline (lint + test + coverage)
yarn analyse:cicd

High-Level Architecture

The application follows a layered architecture with clear separation between the Express server (routing, auth, proxy) and the React client (UI, state, API calls).

Key Architectural Principles

• HATEOAS-driven: The backend returns hypermedia links; the client follows them to discover next actions
• Composition over inheritance: Root SimoStore composes 18 child stores
• Single context: Entire store tree shared via one SimoContext
• Middleware-first server: Express middleware handles auth, proxy, caching, flags before serving the SPA
• Feature flag-gated: All new features behind LaunchDarkly flags for safe rollout

Architecture Views

This repo usually needs two explanations: one for product and delivery stakeholders who want to understand the customer journey, and one for engineers who need to understand runtime control flow.

Express Server

The production server (src/server/production/server.ts) uses a carefully ordered middleware chain. Order matters — changing it can break auth, caching, or routing.

Middleware Chain (Production)

Dynamic Client Injection

The server injects configuration into window.VFUK.env at runtime:

window.VFUK.env = {
  FEATURE_FLAGS: { showAddonPage: true, showMidContractRise: false, ... },
  ENVIRONMENT: 'prod1-green',
  TRACKING_ENVIRONMENT: 'prod',
  TEALIUM_REINVENT: 'https://tags.tiqcdn.com/utag/vodafone/uk-reinvent/prod',
  AUTH_COOKIE_PREFIX: 'eShop-auth',
  DATA_DOG_RUM_APPLICATION_ID: '...',
  DATA_DOG_RUM_CLIENT_TOKEN: '...',
  BUILD_NUMBER: '12345',
  ASSET_URL: 'https://cdn.vodafone.co.uk',
  CDN_DOMAIN: 'https://cdn.vodafone.co.uk',
  // ... and more
}

Why the Node Web Server Exists

• It makes a React SPA behave like part of a larger Vodafone platform, not like a standalone static site.
• It owns auth redirects, callback handling, anonymous session creation, and platform cookie plumbing.
• It proxies platform APIs so the browser does not need to know AWS gateway details, keys, or host headers.
• It injects runtime-only values such as feature flags, Datadog tokens, asset domains, and environment names into window.VFUK.env.
• It optionally prerenders pages and caches HTML so the first paint can arrive before the client app finishes booting.

Detailed Middleware Responsibilities

Proxying & Query Parameters

There are two distinct kinds of proxying in this repo. One is page-level proxying used in local and PR/debug contexts so only SIMO routes are served locally. The other is API proxying, where the Node layer forwards approved endpoints to Vodafone backends.

dxlProxyConfig = {
  apiGateway: {
    defaultChannelId: 'eShop-simo',
    config: {
      'eShop-simo': {
        apiKey,
        environment,
        host,
        url,
      },
    },
  },
  timeout: 30000,
}

React Client

Bootstrap Process (src/client/index.tsx)

SourceProvider (theme-ws10, i18n, assets)
  └─ StyleSheetManager (shouldForwardProp filter)
       └─ Provider (constate wrapper)
            └─ Router / BrowserRouter
                 └─ AppRoutes

Component Architecture

This inventory is based on the current top-level component tree: 11 atoms, 45 molecules, 7 organisms, 10 CRO components, 1 seamless-migration component, and 14 templates.

Render Tree Breakdown

This section is different from the inventory above. It follows the actual runtime ownership chain from route wrapper to page bootstrap to root template to direct child components, and labels what mainly drives each piece.

Route → Page → Template Diagram

Visual tree showing how routes map to pages, which instantiate templates, which compose step templates.

graph TD
  subgraph "HeaderFooterTemplate (outlet)"
    HFT["HeaderFooterTemplate"]
    HFT --> SIMO_CON["/sim-only/best-sim-only-deals → Simo"]
    HFT --> SIMO_BIZ["/business/business-sim-only → Simo"]
    HFT --> SIMO_SHELL["/sim-only/...-shell → Simo (non-prod)"]
    HFT --> P2P_B["/migration/basics/test → P2PMigration (non-prod)"]
    HFT --> P2P_P["/migration/phase5/test → P2PMigration (non-prod)"]
    HFT --> NF["* → NotFound"]
  end

  subgraph "SeamlessHeaderFooterTemplate (outlet)"
    SHFT["SeamlessHeaderFooterTemplate"]
    SHFT --> SM["/customer-transfer/best-sim-only-deals → SeamlessMigration"]
  end

  SIMX["/sim-only/.../simx-details → SimxDetails (no wrapper)"]
  PD["/sim-only/.../:planId/plan-details → PlanDetails (no wrapper)"]

  SIMO_CON --> ST["SimoTemplate"]
  SIMO_BIZ --> ST
  SIMO_SHELL --> ST

  ST --> SPT["SimoPlansTemplate"]
  ST --> SRT["SimoReviewTemplate"]
  ST --> SET["SimoExtrasTemplate"]
  ST --> SIT["SimoInsuranceTemplate"]

  SM --> SMT["SeamlessMigrationTemplate"]
  SMT --> SMPT["SeamlessMigrationPlansTemplate"]

  P2P_B --> P2PT["P2PMigrationTemplate"]
  P2P_P --> P2PT
  P2PT --> P2PPT["P2PPlansTemplate"]

  PD --> PDT["PlanDetailsTemplate"]
  SIMX --> SIMXT["SimxDetailsTemplate"]
          

MobX Store Architecture

State management uses a composition pattern. The root SimoStore creates and holds 18 child stores. Each child keeps a back-reference to the root.

Key Root Store State

// Journey & Segment
journeyType: 'acquisition' | 'upgrade' | 'secondline' | 'p2p'
journeySubType: 'seamlessMigration' | ''
segment: 'consumer' | 'business'
isSeamlessMigration: boolean

// Plans & Commerce
plans: Plan[]
basketTotal: { buildSteps, cta, monthlyCost, upfrontCost }
summary: SubscriptionSummary   // existing contract (upgrades)
loyalty: { discountAmount, preText, postText, value, uom }

// UI State
error: Simo.Error | null
errorCode: string | null
showLoginNotification: boolean

MobX Pattern

class MyStore {
  someValue = ''
  
  constructor(private simoStore: SimoStore) {
    makeObservable(this, {
      someValue: observable,
      derivedValue: computed,
      updateValue: action,
    })
  }

  get derivedValue() { return this.someValue.toUpperCase() }
  
  updateValue(val: string) { this.someValue = val }
}

MobX & React Context

This repo uses one React context to carry one root store object. MobX is then responsible for deciding which observer components need to rerender.

Plan Filtering & Visibility

The app does not simply dump journey.plans onto the screen. It refetches plans from the backend when filters change, then applies a smaller set of frontend-only merchandising rules.

What gets filtered out and why

Add-ons & Accessories Flow

What people usually call the add-ons step is actually two related mechanisms: the journey extras page driven by GET_EXTRAS, and a separate insurance / device cross-sell path that talks to device add-on APIs.

API Services

Service Map

API URL Construction

// Base pattern
/api/digital/v1/{platformSessionId}/simo-purchase/journeys

// Where platformSessionId comes from the auth session cookie
const session = getSession()
const url = `/api/digital/v1/${session.platformSessionId}/simo-purchase/journeys`

Error Handling Pattern

import to from 'await-to-js'

const [err, data] = await to(apiCall())

if (err) {
  logger.error(
    DD_LOG_MAP[DD_ERRORS.GET_PLANS_VARIANT],
    'simOnlyService.getPlans',
    { links, journeyType },
    err
  )
  return Promise.reject({ ...err, step: 'getPlans' })
}

return data

simOnlyService: what it actually does

makeAPIRequest / runHateoasLink()

OTB: Options To Buy

packageBuildSummary.buildSteps: what it is and where it is used

Plan Details Deep Dive

The plan details experience has two separate surfaces that reuse the same content-mapping ideas. The first is the in-journey modal opened from the plan list. The second is the dedicated route page at /sim-only/best-sim-only-deals/:planId/plan-details. Both use the same underlying CMS sources, but they render them in different containers and bootstrap in different ways.

How each tab gets rendered

1. Overview tab: does not use CMS plan-details content. It renders directly from the selected plan object, including name, benefit items, price, badge, entertainment promo, and the select-plan button.
2. What’s included: uses getContentForPlan, which is the orchestration helper for the most complex tab.
3. Additional charges: uses getPlanDetailsTabContent with the page-specific plan-content collection.
4. What you need to know: also uses getPlanDetailsTabContent.
5. About speed: also uses getPlanDetailsTabContent.

What this object means in the modal

planDetails: {
  sharedPlanDetails,
  pageSpecificPlanDetails,
}

This is the core input to the plan-details content resolver. sharedPlanDetails contains the reusable overlay content loaded from the shared journey-app asset plan_details_overlay_app. pageSpecificPlanDetails is the shop-page-specific plan-content entry for the current page and segment. The helpers combine both because some content is generic and some is page or plan-subtype specific.

How ContentStore feeds all plan-details calls

The content store prepares plan-details data in multiple places, depending on which journey is loading.

1. Main SIMO load: fetchContent() requests the shop-page content, planDetailsOverlay, and supporting assets.
2. P2P load: fetchP2PContent() does the same pattern for P2P-specific content.
3. Seamless migration load: fetchSeamlessMigrationContent() repeats the pattern for the seamless page.
4. Plan-details route load: loadPlanDetailsContent() is the route-specific bootstrap path and fetches just the content needed for the standalone page.

In all of these paths, the important request is the same: planDetailsOverlayRequest. That request fetches the shared overlay asset and stores it as content.planDetailsOverlay. The content store then also resolves planContent from the shop-page asset, which becomes the page-specific input used by the tab helpers.

What is the planListContent prop?

There is not a prop literally named planListContent in the plan-details modal flow. The naming usually refers to one of two things:

• The PlanListContent component: this is the component that renders the plan cards and is the source of the modal-opening interaction.
• The plan-list CMS content: this is passed as content={get(content, ‘planList’)} and planContent={content} into the component.

The important prop for plan-details is actually planContent on PlanListContent. That object feeds the plan-card mapper, which enriches raw plans with UI-facing fields that are later used when a plan is opened in the modal.

How the modal flow works end to end

1. SimoPlansTemplate renders PlanListContent and passes plan-selection and modal-tracking callbacks into it.
2. PlanListContent maps raw plans through plansCardMapper and renders PlanCardList.
3. A plan card calls openPlanListModal({ ...plan, buttonName, buttonState }) when the user clicks See plan details.
4. PlanStore.openPlanListModal stores that enriched plan in planListModal and sets isPlanListModalOpen.
5. SimoTemplate renders PlanCardDetailsModal when the flag is open.
6. PlanCardDetailsModal reads the selected plan from planStore.plans, constructs tabs, and calls the content helpers for each tab.
7. The non-overview tabs render through PlanDetailsOverlayModal, which simply hands CMS-shaped content to HeadingAndContent.

How getContentForPlan works

getContentForPlan is the orchestrator for the tab content and especially for the What’s included tab.

1. If no plan exists, it returns an empty array early.
2. It calls getPlanDetailsHelper(plan, sharedPlanDetails) to find the shared overlay group based on type and band.
3. If the tab is not whatsincluded, it delegates to getPlanDetailsTabContent.
4. For whatsincluded, it checks whether airtime-benefit content exists in the shared overlay content.
5. It optionally pulls SIMX benefit content.
6. If airtime content exists, it merges plan benefits and subtype-specific shared-plan-group content.
7. If no airtime content exists but a subtype exists, it tries a page-specific packagelistsimo_${‘{subType}’} entry.
8. If all else fails, it falls back to packagelistsimo_essentials.

Each helper in getPlanDetailsContent

What happens if we add a new plan.type or subType?

Yes, that can affect content resolution. Whether existing helpers can be reused depends on whether the new type or subtype can map onto the current CMS key strategy.

• If the new subtype is only another alias of an existing content family, you can usually reuse the current helpers by extending SUBTYPES or getPlanSubType.
• If the new type changes the GB vs UNLTD assumption, you will likely need to update getAirtimePlanType and possibly the shared CMS key structure.
• If the new subtype needs its own page-specific CMS block, a matching packagelistsimo_${‘{newSubtype}’} entry will be needed.
• If the new plan requires its own benefit-item rules, you may also need new shared overlay entries and possibly an update to getPlanBenefits.

Plan-details analytics events

The modal does not send analytics directly from the UI component alone. It writes state into PlanDetailsStore, and the analytics reaction layer watches that state.

• Plan details opened: trackPlanDetailsModalOpen writes modal-open state, then linksSimoPlanDetails sends a link event and a product-view event.
• Tab changed: trackPlanDetailsModalTabChange writes tab state, then the same analytics reaction sends a tab event.
• Modal closed: trackPlanDetailsModalClose clears overlay page config. This updates page state rather than firing the same link/tab event pattern.
• Select plan from overview tab: the overview button calls selectPlanListModalPlan, which routes into PlanStore.selectPlan. The actual plan-selection analytics are then handled by the broader choosePlan reaction, not the plan-details reaction.
• Add-on details modal: separate tracking exists via trackPlanDetailsAddOnModalOpen and trackPlanDetailsAddOnModalTabChange.

What the dedicated route is for

<Route path=’/sim-only/best-sim-only-deals/:planId/plan-details’ element={<PlanDetails />} />

• This route provides a full-page, deep-linkable plan-details experience instead of an overlay modal.
• It creates a fresh SimoStore, reads planId from the URL, and runs store.initPlanDetails(planId).
• It then renders PlanDetailsTemplate and uses the same helper family to resolve the tab content.
• It is not exactly the same UI as the modal because it lives in a dedicated page shell rather than inside Modal and TabbedModalTemplate.
• It is still based on the same underlying content concepts: overview data from the plan object, and tab content from shared and page-specific CMS assets.

Contentful / CMS Content Architecture

The repo has two distinct Contentful paths. The main client path is driven by ContentStore and contentServiceV2.getAssetModelV2() for page content. A separate server path uses contentAPITransformer for shell content such as header navigation and footer.

Two Content Pipelines

Client Content Fetch Flow

Actual Client Request Shape

const searchParams = new URLSearchParams({
  contentEntryKey,
  contentType,
  spaceName: 'consumer',
})

requestInstance(`/api/content-service/v2/content?${searchParams.toString()}`)
  .get()

What ContentStore Actually Does

Main Helpers and Constants

How Responses Are Mapped

mapPageContent() is the core transformation function inside ContentStore. It uses CONTENTFUL_PATH_CONFIG to pull large branches out of the raw response, then repeatedly uses findByContentEntryKey() to extract specific entries.

const channelAppContent = get(
  pageContent,
  `${CONTENTFUL_PATH_CONFIG.basePath}.${CONTENTFUL_PATH_CONFIG.channelApp}.fields.content`,
  [],
)

const reviewHeaderContent = findByContentEntryKey(
  channelAppContent,
  CONTENTFUL_CONTENT_ENTRY_KEYS.reviewHeader,
)

const secureNetContent = findByContentEntryKey(
  channelAppContent,
  CONTENTFUL_CONTENT_ENTRY_KEYS.secureNetUspContent,
)

Dynamic CMS Fetches and Caching

Not every CMS request happens at initial page load. Some assets are fetched later from HREFs returned by other content, then cached in cachedContent by segment.

cachedContent: Map<segment, Map<contentName, resolvedContent>>

getContentByHref(contentName, href)
  - parses contentEntryKey + contentType from the href
  - calls getAssetModelV2(...)
  - stores the resolved content under the current segment

getHighlandsDynamicContentByHref(productId, href)
  - parses contentEntryKey + contentType
  - avoids duplicate fetches for the same product
  - appends the fetched modal content into highlandsModalContent

Server-Side Header/Footer Content Flow

The server has a separate Contentful path for shell assets. This is the only place in the repo where spaceName is already varied between consumer and business without changing the client content service.

businessFooter: {
  v2: {
    assetName: 'business_footer',
    assetType: 'footer',
    spaceName: 'business',
  },
}

How to Add a New Contentful Call

Case 1: New content in the existing client path

1. Add a constant to CONTENTFUL_CONTENT_ENTRY_KEYS if the new CMS asset will be looked up by key inside a larger page response.
2. If you need a new response path, add it to CONTENTFUL_PATH_CONFIG.
3. Add a new hydrate(...) request in the relevant ContentStore fetch method such as fetchContent(), fetchSeamlessMigrationContent(), or fetchP2PContent().
4. Include the request in the surrounding Promise.all.
5. Map the returned payload inside loadContent() or mapPageContent() so components can read it from consumerContent or businessContent.
6. If the content is rendered conditionally, route it through helpers like findByContentEntryKey() and shouldShowContentByTag() instead of duplicating traversal logic in components.
7. If the content should work in local dev without live CMS access, update mocks or fixtures as needed.

Case 2: You actually need a new client-side spaceName

The current client service cannot do this without code changes because spaceName is fixed to consumer. To support a new value, you would need to:

1. Extend ContentParams in getAssetModelV2.ts with spaceName?: string.
2. Default it safely, for example spaceName = 'consumer', so current call sites keep working.
3. Pass the new spaceName from the specific ContentStore fetch path or new caller that needs it.
4. Add tests for the new query-string behavior in getAssetModelV2.test.ts.
5. Only do this if a new Contentful space is really required; in this repo, most business-vs-consumer variation is already handled through entry keys, not through the client-side spaceName.

export interface ContentParams {
  contentEntryKey: string
  contentType: string
  spaceName?: string
}

const getAssetModelV2 = ({ contentEntryKey, contentType, spaceName = 'consumer' }: ContentParams) => {
  const searchParams = new URLSearchParams({ contentEntryKey, contentType, spaceName })
  return requestInstance(`/api/content-service/v2/content?${searchParams.toString()}`).get()
}

Case 3: New server-side shell asset with its own spaceName

1. Add a new entry to src/server/common/config/contentAPITransformer.config.ts.
2. Set the correct assetName, assetType, and spaceName in the v2 config.
3. Ensure the server middleware path that consumes it is already covered by the current transformer configuration flow.

Routing

Request Lifecycle

Here's what happens when a user visits /sim-only/best-sim-only-deals:

Prerendering

Prerender is a backend HTML-caching feature. The server can return already-rendered markup for a page, and the React app then hydrates that HTML instead of starting from a blank root.

Authentication Flow

Authentication is handled through Vodafone IDM. The app can serve both anonymous and authenticated users, but some journeys or actions require a stronger logged-in state.

What IDM is and why this app uses it

IDM OAuth2 Flow

Auth Configuration

{
  loginScope: 'openid vf-profile vf-account vf-subscription vf-contact',
  authLevel: 3,              // Highest assurance
  dualMode: true,            // Allow both auth + anon
  channelId: 'eShop-simo',   // DXL channel identifier
  basePath: '/web-shop/login'
}

HATEOAS API Pattern

The backend uses Hypertext As The Engine Of Application State. Instead of hardcoding API URLs, the client discovers endpoints dynamically from response links.

How It Works

Code Example

// Step 1: Create or retrieve journey
const journey = await journeyService.createReinventJourney({
  journeyType: 'acquisition',
  platformSessionId,
})

// Step 2: Journey response includes _links
// { _links: { 'get-plans': { href: '...', method: 'GET' }, ... } }

// Step 3: Use link to fetch plans
const plans = await simOnlyService.getPlans({
  links: journey._links,
  journeyType: 'acquisition',
  userType: 'consumer',
})

Common HATEOAS Link Names

• GET_PLANS
• SELECT_PLAN
• GET_SUBSCRIPTION_SUMMARY
• GET_OTB
• SET_JOURNEY_TYPE
• SET_OPERATION_MODE
• GET_EXTRAS
• SELECT_EXTRA
• REMOVE_EXTRA
• ADD_BYOD_INSURANCE
• GET_PLAN_DETAILS

Journey Initialization

When the Simo page mounts, SimoStore.initJourney() orchestrates the entire setup sequence:

Journey Types

All API Calls — Quick Reference

Every HTTP call the frontend makes goes through the Express proxy (dxlProxyMiddleware) to the AWS DXL API Gateway. The frontend never talks to backend services directly. All calls are discovered via HATEOAS links returned in previous responses — the frontend holds no hardcoded backend URLs except the initial journey entry point.

Journey Init & Resume

Starting a journey — what happens on page load

SimoStore.initJourney() decides which journey call to make based on URL query params and journey type:

// Decision logic (SimoStore.ts)
if (packageId) {
  // Returning user with an existing package
  → getSimoJourneyForPackage(packageId)
    GET .../journeys?packageId={packageId}

} else if (isP2P) {
  → getSimoJourneyLatestP2P...()
    GET .../journeys/latest?segment=...&planType=BASICS|PHASE5

} else if (isSeamlessMigration) {
  → getSeamlessMigrationJourneyLatest()
    GET .../journeys/latest?transactionId=...&journeySubType=seamlessmigration

} else {
  // Standard acquisition / upgrade
  → getSimoJourney()
    GET .../journeys/latest?segment=consumer|business[&referrer=...]
}

Journey Latest — example response (key fields)

{
  "id": "abc-123-journey-id",
  "journeyType": "acquisition",           // or "upgrade" | "secondline" | "tariffMigration"
  "segment": "consumer",
  "operationMode": "SINGLE",
  "state": "Created",                     // or "Created,planSelected" if plan was previously chosen
  "packageBuildSummary": {
    "monthlyPrice": { "gross": { "value": 0 } },
    "upfrontCost":  { "gross": { "value": 0 } },
    "buildSteps":   []                    // Empty until plan selected
  },
  "notification": [],                     // Mismatch/warning codes if any
  "_links": {
    "get-plans": {
      "href": "/simo-purchase/paym/v2/{sessionId}/journeys/abc-123/plans",
      "type": "GET",
      "queryParameters": { "commitmentPeriod": "24 Months", "segment": "consumer" }
    },
    "get-offers-and-buy-options": { "href": "...", "type": "GET" },
    "set-operation-mode": {
      "href": "...", "type": "POST",
      "parameters": { "operationMode": "SINGLE" }
    }
  }
}

Returning user — plan already selected

When a user previously selected a plan (e.g. left the browser tab open, or returns with the same session), the journey state field tells the frontend what's already done:

// state values (comma-separated, cumulative):
"Created"                                   // Fresh journey
"Created,planSelected"                      // Plan was chosen
"Created,planSelected,extraSelected"        // Plan + extras chosen

The plans response will also include a selectedPlan field with the full plan object. PlanStore uses this to highlight the already-selected card and pre-populate the basket summary.

URL query param — resuming a specific package

If ?packageId=xxx is present in the URL (e.g. user navigated back from basket), the app calls getSimoJourneyForPackage() instead of latest. This retrieves the journey associated with that package, restoring the full selection state.

GET /api/.../journeys?packageId=abc-package-id
// Response includes: selectedPlan, packageBuildSummary with steps completed

Plans API

The plans call is made immediately after the journey is initialised, and again any time filters change. The URL is taken directly from the journey's _links["get-plans"] — the frontend never constructs this URL itself.

What the frontend sends

// The HATEOAS link already contains the base query params (e.g. commitmentPeriod).
// FilterStore merges in any user-selected filter values before firing:

GET /api/digital/v2/simo-purchase/paym/v2/{sessionId}/journeys/{journeyId}/plans
  ?commitmentPeriod=24+Months
  &sortBy=monthlyPrice.asc     // (optional, if user sorted)
  &segment=consumer

Example response (trimmed)

{
  "plans": [
    {
      "id": "plan-001",
      "name": "Unlimited Lite",
      "type": "airtime",
      "subType": "Unlimited",
      "commitmentPeriod": "24 Months",
      "monthlyPrice": { "gross": { "value": 1200 } },   // pence
      "dataInfo":  { "prefix": "", "main": "Unlimited" },
      "priceInfo": { "unit": "£", "text": { "main": "12.00", "suffix": "/month" } },
      "benefitItems": {
        "benefitItems": [
          { "productId": "030060", "name": "Wi-Fi Calling" },
          { "productId": "050100", "name": "Entertainment" }
        ]
      },
      "inclusiveProducts": [
        { "id": "030060", "name": "Wi-Fi Calling" }
      ],
      "isRecommended": false,
      "isSelected": false,
      "_links": {
        "select-plan": {
          "href": "/simo-purchase/paym/v2/{sessionId}/journeys/{id}/package/plan",
          "type": "POST",
          "parameters": { "planId": "plan-001", "linesQuantity": 1 }
        }
      }
    }
  ],
  "selectedPlan": null,           // Non-null if plan already selected (returning user)
  "filters": {
    "commitmentPeriod": [
      { "value": "12 Months", "totalNoOfPlans": 5 },
      { "value": "24 Months", "totalNoOfPlans": 8 }
    ]
  },
  "sortBy": ["monthlyPrice.asc", "monthlyPrice.desc"],
  "noOfFiltersApplied": 0
}

Memoisation

getPlans() is wrapped with memoize() (maxSize: 8, deep-equal key). Identical filter states do not fire a second network request — the cached promise is returned. The cache is per-call-signature, not persisted across page loads.

Plan Selection Flow

What happens when the user clicks "Choose"

What is sent

// POST body is taken from plan._links["select-plan"].parameters:
{
  "planId": "plan-001",
  "linesQuantity": 1       // 1 for consumer; 2–5 for business multi-line
}

What comes back

{
  "packageBuildSummary": {
    "monthlyPrice": { "gross": { "value": 1200 } },
    "upfrontCost":  { "gross": { "value": 0 } },
    "buildSteps": [
      { "name": "Plans",    "completed": true },
      { "name": "Add-ons",  "completed": false },
      { "name": "Review",   "completed": false }
    ]
  },
  "state": "Created,planSelected",
  "_links": {
    "get-extras":              { "href": "...", "type": "GET" },
    "select-keep-package":     { "href": "...", "type": "POST" },
    "select-replace-package":  { "href": "...", "type": "PATCH" }
  }
}

How the plan persists across sessions

After a plan is selected, the backend associates it with the journey via its own persistence layer. The next time the user arrives (same session or new session with the same authenticated account), journeys/latest returns state: "Created,planSelected" and the selectedPlan field is populated in the plans response. The frontend has no role in persisting the selection — it only reads back what the backend reports.

KeepOrReplaceStore — Basket Conflict

When a logged-in user selects a plan, the backend may detect that their basket already contains a package from a previous session. The backend signals this via a notification code in the journey response, and the frontend shows a modal asking the user what to do.

When it appears

// SimoStore — after plan selection response:
if (shouldShowPackageModal(journey)) {
  this.keepOrReplaceStore.errorCode = journey.notification[0].code
  this.keepOrReplaceStore.links     = journey._links
  // → Modal is displayed
}

The two choices

POST select-keep-package
// No extra body — HATEOAS params only
// Response: basket now has both plans

PATCH select-replace-package
{ "planId": "plan-001" }
// Response: basket has only the new plan

What KeepOrReplaceStore manages

• errorCode — the notification code from the backend (drives the modal copy)
• links — the _links from the journey response, used to call keep or replace
• onKeepOrReplace(replacePackage) — calls the appropriate service and resolves the conflict

MismatchStore — Segment & Session Conflicts

A mismatch is when the backend detects that the current journey context is incompatible with the user's account or basket state. It is different from a Keep/Replace conflict — mismatches are about the user's identity or eligibility, not their basket contents.

Common mismatch scenarios

Resolution API calls

// Continue in new segment (clear extras from old segment):
POST sync-bskt-seg-to-jrny
// → Journey switches segment, extras cleared, plans refetched

// Cancel — revert to original segment:
POST sync-jrny-seg-to-bskt
// → Journey reverts, user stays on original segment

// Empty basket and start fresh:
POST empty-basket
// → All basket contents cleared, journey reset to "Created"

What MismatchStore manages

• errorCode — notification code from backend; drives which modal variant is shown and which CMS copy loads
• continueAndClearExtras() — calls changeJourneySegment() then refetches plans
• cancelSwitchSegment() — calls keepJourneySegment()
• emptyBasketAndContinue() — calls emptyBasket() then reloads the journey

Extras / Add-ons API

Loading extras

// ExtraStore.loadExtras() → simOnlyService.getExtras(links)

GET (via get-extras HATEOAS link)
/simo-purchase/paym/v2/{sessionId}/journeys/{journeyId}/package/extras
  [?linesQuantity=2]    // only for multi-line business

// Response:
{
  "available": [
    {
      "id": "extra-001",
      "name": "Roam Further",
      "description": "Use your data in more countries",
      "monthlyPrice": { "gross": { "value": 500 } },   // pence
      "isSelected": false,
      "_links": {
        "select-extra": { "href": "...", "type": "POST", "parameters": { "extraId": "extra-001" } },
        "remove-extra":  { "href": "...", "type": "DELETE", "parameters": { "extraId": "extra-001" } }
      }
    }
  ],
  "packageBuildSummary": { "monthlyPrice": { ... }, "buildSteps": [...] },
  "notifications": []
}

Selecting / removing an extra

// ExtraStore.toggleExtra(extra)
// If extra.isSelected === false  → selectExtra  → POST select-extra
// If extra.isSelected === true   → removeExtra  → DELETE remove-extra

// After either call, loadExtras() is called again to get the updated list
// The response to select/remove itself is not used — the follow-up GET provides fresh state

Extra detail content (CMS)

Each extra has optional "What's included" detail content loaded from Contentful. ExtraStore.getExtraContent(extra) looks up the CMS key extraswhatsincluded_sku{extra.id} from the pre-loaded packagelistsimoextraswhatsincluded content block. If no CMS entry exists for that ID, the detail link is hidden.

// Key pattern:
`extraswhatsincluded_sku${extra.id}`
// e.g. "extraswhatsincluded_skuROAM001"
// If no match → extra.includeViewDetails = false

Insurance API

Insurance is a separate add-on flow, distinct from extras. It requires the user to select a device (Bring Your Own Device) before a price can be shown.

1. Get available insurance options

// InsuranceStore.getInsuranceAddons()
// URL is NOT from HATEOAS — it is constructed directly:

GET /sim-only/best-sim-only-deals/api/device-xsell-purchase/v1/addOns/SIMO/consumer/acquisition
  ?addOnRequestType=INSURANCE
  &deviceId={deviceId}
  &insuranceInBasketCount={count}    // from journey HATEOAS link param

// Response:
{
  "bingoInsurances": {
    "insuranceOptions": [
      {
        "id": "insurance-001",
        "name": "Total Care",
        "monthlyPrice": { "gross": { "value": 899 } },
        "stepPrices": [                              // Multi-step pricing (promotional)
          { "price": { "consumer": 499 }, "label": "Months 1–3", "upToMonth": 3 },
          { "price": { "consumer": 899 }, "label": "Month 4+",   "afterMonth": 3 }
        ]
      }
    ],
    "insurancePromotionEligibility": "MULTILINE"
  }
}

2. Load device list (BYOD)

// InsuranceStore.getDevices()
// Uses HATEOAS link "get-BYODeviceList" if present; otherwise hardcoded fallback:

GET /api/digital/v2/productCatalog/device/BYODeviceModel/deviceType/handset

// Response:
{
  "BYODeviceList": [
    {
      "displayModel": "iPhone 15 Pro",
      "make": "Apple",
      "memoryVariants": [
        {
          "memory": "128GB",
          "colorVariants": [
            {
              "color": "Black",
              "genericDeviceId": "dev-sku-001",
              "oracleAssurantId": "assurant-001"   // Required for insurance submission
            }
          ]
        }
      ]
    }
  ]
}

3. Submit insurance

// InsuranceStore.submitInsuranceDetailsFn()
// Uses HATEOAS link "add-byod-insurance" if present (updating existing insurance);
// otherwise constructs URL directly (first-time submission):

POST .../journeys/{journeyId}/package/insurance
{
  "insuranceId":   "insurance-001",
  "deviceInfo": {
    "deviceName":       "iPhone 15 Pro",
    "make":             "Apple",
    "model":            "A2846",
    "memorySize":       "128GB",
    "deviceColor":      "Black",
    "imei":             "123456789012345",    // User-entered
    "genericDeviceSkuId": "dev-sku-001",
    "assurantId":       "assurant-001"
  }
}

Feature Flags

LaunchDarkly flags are fetched server-side, injected to the client, and mirrored into MobX state via FeatureFlagStore.

Flag Lifecycle

Local Override Methods

// Method 1: Cookie
document.cookie = 'features=showMidContractRise=true,showTrendingPlans=true'

// Method 2: Query parameter
https://localhost:8000/sim-only/best-sim-only-deals?features=showMidContractRise=true

All flags

Cookie Management

Default cookie prefix: eShop-auth (configurable via AUTH_COOKIE_PREFIX env var).

Session Management

Session data is extracted from the {prefix}_p_id_token cookie by the getSession() helper:

const session = getSession()
// Returns:
{
  assuranceLevel: 3,              // Auth confidence (0-3)
  givenName: 'John',             // User first name
  numberOfAccounts: 1,
  numberOfSubscriptions: 2,
  accountCategory: 'Consumer',   // or 'Business'
  subscriptionIdHash: 'abc...',
  phoneNumberHash: 'def...',
  subscriptionType: 'PAYM',      // Pay Monthly
  platformSessionId: 'UUID',     // Used in API URL construction
}

When the Journey Starts (Initialization Flow)

When a user lands on the SIM-only landing page (such as /sim-only/best-sim-only-deals), the application initializes a purchase journey. Here is exactly what is set, read, and invoked during this lifecycle sequence:

await authService.session()

Environment Variables

Server-Side (process.env)

Client-Side (window.VFUK.env)

These are injected by the server at runtime into the HTML page — not build-time constants:

FEATURE_FLAGS          // Object of all 45+ flag values
ENVIRONMENT            // 'prod1-green', 'int1-blue', etc.
TRACKING_ENVIRONMENT   // 'prod' or 'dev'
AUTH_COOKIE_PREFIX     // 'eShop-auth'
BUILD_NUMBER           // CI build number
ASSET_URL              // CDN URL for assets
DATA_DOG_RUM_*         // Datadog application/client tokens
USE_DD_BROWSER_LOGS    // Enable browser logging
DD_CLIENT_TOKEN        // Datadog client token

Development Server & AIM Mocking

Dev Server Features

• HTTPS by default (self-signed cert)
• Vite HMR for instant updates
• AIM mock replay for offline development
• Debug panel for selecting mock profiles
• Simplified DXL auth (no real OAuth flow needed)
• Routes not in whitelist proxy to live environment

AIM (API Interaction Mock)

AIM records and replays API responses from __mockapi__/ so you can develop without a live backend.

AIM Naming & Matching Conventions

Tooling (NPS / Vite)

The repo does not wire commands directly by hand in every case. It uses NPS as the high-level script entrypoint, shared Vodafone boilerplate script factories underneath, and Vite as the client build / dev toolchain.

Testing

Jest Unit Tests

Test Utilities

import { render, renderWithContext } from '@helpers/testUtils/testUtils'

// Standard render (wraps with SourceProvider + OverlayProvider)
render(<MyComponent />)

// With SimoStore context
const mockStore = { plans: [...], segment: 'consumer', ... }
renderWithContext(<MyComponent />, mockStore)

Cypress E2E Tests

Build & Deployment

Standard Build (Vite)

The standard app build uses Vite with React plugin, CSS modules, and path alias resolution.

Federated Build (Micro-Frontend)

# Builds SystemJS bundle for single-spa shell integration
yarn build:federated

# Output: =build/federated/vfuk-shop-simo.js
# Entry: src/client/index.federated.tsx
# Lifecycle exported: bootstrap → mount → unmount

CI/CD Pipeline

Pipeline definitions in cicd/ — build, PR validation, merge, release, and Renovate bot configs.

Renovate

Renovate is the repo's automated dependency-update bot. In this codebase it is configured for Azure DevOps, groups updates into predictable PRs, and deliberately disables certain risky upgrades so dependency maintenance stays reviewable.

Observability

Datadog logging

try {
  await to(authService.session())
} catch (e) {
  logger.error(
    DD_LOG_MAP[DD_ERRORS.SESSION_UNAVAILABLE],
    'src/client/index',
    {},
    e,
  )
}

Log Categories

• Session/Auth
• Journey CRUD
• Plans fetch/select
• Extras toggle
• Insurance
• Content/CMS
• Filters
• Checkout
• Seamless Migration

Tealium Analytics

• 70+ tracked events via @vfuk/lib-web-analytics
• Events: page loads, overlay views, link clicks, cart add/remove, filter actions
• Action types: BUTTON, LINK, TAB, DROPDOWN, ACCORDION, CAROUSEL, TOGGLE
• Configuration in src/client/analytics/analyticsConfig.ts

OneTrust

Consent management scripts injected before all other third-party scripts. Controls what tracking is allowed.

File Structure

Path Aliases

These aliases are configured in three places that must stay in sync: tsconfig.json, babel.config.js, and tools/vite/.

Constants & Globals

Journey Types

const JOURNEY_TYPES = {
  ACQUISITION: 'acquisition',
  UPGRADE: 'upgrade',
  SECONDLINE: 'secondline',
  TARIFF_MIGRATION: 'tariffMigration',
  P2P: 'p2p',
}
// Plus: journeySubType = 'seamlessMigration'

Segments

'consumer' | 'business'

Key URLs

URLS = {
  SIMO: '/sim-only/best-sim-only-deals',
  BUSINESS_SIMO: '/business/business-sim-only',
  CUSTOMER_TRANSFER: '/customer-transfer/best-sim-only-deals',
  UPGRADES_AND_OFFERS: '/upgrade-and-offers',
  LOGIN: '/web-shop/login',
  LOGOUT: '/web-shop/logout',
  BASKET: '/basket',
}

API Constants

BASE_URL = '/api/'
HAL_JSON = 'application/hal+json'
MICROSERVICE_TYPE = 'simo-purchase'
DXL_CHANNEL = 'eShop-simo'

Mismatch / Error Codes

SESSION_EXPIRED_LOGIN_OR_EMPTY_BASKET
NOT_ELIGIBLE_SEGMENT_DEEPLINK
LMS_DOWN_DEEPLINK
RECOMMENDED_PLAN_NOTIFICATION
LOST_SMARTWATCH_BENEFIT

Key Packages

UI & Design System

State & Data

Auth & Session

Observability

Content & i18n

Build & Testing

Journey Latest & Commitment Period

Who controls whether 12-month or 24-month plans are shown on initial load?

Flow

The one frontend override: Basic Upgrade

In simOnlyService.ts, when the journey is detected as a basic upgrade (isBasicUpgrade), the frontend rewrites the link before following it, replacing 24+Months with 12+Months:

// src/client/services/simOnlyService/simOnlyService.ts
href: plansLink.href.replace('24+Months', '12+Months'),
parameters: { ...plansLink.parameters, commitmentPeriod: '12 Months' },
queryParameters: { ...plansLink.queryParameters, commitmentPeriod: '12 Months' },

All other commitment-period changes (user switching from 12 to 24 months via filter tabs) go through FilterStore, which rebuilds the GET_PLANS query string and re-requests plans from the backend. The frontend never hard-codes an initial value independently.

3onv consideration

Backend ID → CMS Content Map 3onv Risk

This is the core migration risk for 3onv. Several pieces of visible content on the plan card and plan details modal are resolved by matching a backend-supplied identifier against a Contentful entry key. If the backend sends different IDs for 3onv, those lookups silently return nothing and the content disappears.

Full inventory of backend-to-CMS bindings

Type and subtype constants

The SUBTYPES constant in src/client/stores/helpers/getPlanDetailsContent/constants.ts maps backend plan.subType strings to CMS slug fragments. If 3onv sends different subtype strings, these mappings will fail to resolve.

// constants.ts (representative — check file for full list)
SUBTYPES = {
  'basics plan': 'basics',
  'red plan':    'red',
  // ... other subtypes
}

Band mapping for handset/device details

getUpsellBand() combines plan.upsellBand, plan.planBand, plan.type, and plan.subType to produce a band number (1, 2, or 3). This is combined with GB/UNLTD to build a CMS key like devicedetailshandset_gb_2. If band values change for 3onv, the wrong (or no) handset details will render.

3onv migration options

Plan Card Benefit Items

Benefit items shown on a plan card come from the backend inclusiveProducts array in the plans response, but the display content (icon, label, tags, modal body) comes from Contentful. The two are joined by ID matching at render time.

Backend fields involved

Highlands benefit rendering path

Benefit tags control visibility

Tags on the Contentful benefit entry determine where/how the benefit appears:

• visible — shown in main card benefit list
• modalOnly — only shown inside the plan details modal
• xtra — shown in the Xtra benefits section

Non-Highlands path

Uses orderAndEnrichBenefitItems(). Starts from plan.benefitItems and enriches each item with CMS data by constructing the key benefit_item_{productId}. Tags and display order come from Contentful.

getContentForPlan Helper

File: src/client/stores/helpers/getPlanDetailsContent/helpers/getContentForPlan/index.ts

This is the single function that resolves which CMS content block renders inside the plan details modal for a given plan and tab. It is called once per tab render inside PlanCardDetailsModal.

Inputs

What is pageSpecificPlanDetails.fields.entries?

pageSpecificPlanDetails is the Contentful shopPage for the current segment. It is loaded by ContentStore.loadPlanDetailsContent() using:

// ContentStore.ts
contentServiceV2.getAssetModelV2({
  contentEntryKey: 'packagelistsimo_consumer',  // or 'packagelistsimo_business'
  contentType: 'shopPage',
})

The Contentful shopPage contains a list of child entries (fields.entries). Each entry has a contentEntryKey that the frontend uses as a lookup key. Examples:

findByContentEntryKey(entries, key) simply does an array .find() on these entries matching on contentEntryKey. It returns the first match or undefined.

Internal helper functions (all defined in-file, not exported)

These are const functions defined at the top of getContentForPlan/index.ts. They are not exported or callable from outside this file.

// Returns one of: 'gb_1' | 'gb_2' | 'gb_3' | 'unltd_1' | 'unltd_2' | 'unltd_3' | 'generic'
// The result is appended to 'devicedetailshandset_' to form the CMS lookup key

Decision flow for "What's Included" tab

`devicedetailshandset_${getPlanSubType(plan.subType)}`.toLowerCase()
// e.g. 'devicedetailshandset_unlimited51'

getPlanSubType — what it does

File: src/client/stores/helpers/getPlanDetailsContent/helpers/getPlanSubType/index.ts

getPlanSubType("Unlimited51")
// 1. Not null
// 2. Doesn't include 'simx' → no SIMX stripping
// 3. Not in ['unlimitedMax51','unlimitedMax'] → no alias
// 4. Not in entertainment alias list
// 5. planSubType = "unlimited51" (lowercased)
// 6. SUBTYPES["unlimited51"] = "unlimited51"  ← match found
// → returns "unlimited51"

getPlanSubType("3onv Plan")
// → planSubType = "3onv plan"
// → SUBTYPES["3onv plan"] = undefined
// → undefined?.toLowerCase() = undefined
// → CMS key becomes "devicedetailshandset_undefined" → no match → fallback to essentials

Subtype Reference

File: src/client/stores/helpers/getPlanDetailsContent/constants.ts — SUBTYPES object. These are all the plan.subType values the frontend currently recognises. The key is what the backend sends (lowercased), the value is the slug used in the Contentful entry key.

There are also two alias mappings handled in getPlanSubType() before the table lookup:

• "unlimitedMax51" and "unlimitedMax" → mapped to SUBTYPES.unlimited value directly (bypasses table)
• "unlimitedMaxEntertainment51" and "unlimitedMaxEntertainment" → mapped to SUBTYPES.unlimitedentertainment51 value directly
• Any subtype containing 'simx' → the SIMX prefix/suffix is stripped before the table lookup

Plans Grid Page — Everything Except the Plan Cards

File: src/client/templates/SimoPlansTemplate/SimoPlansTemplate.tsx

SimoPlansTemplate is the top-level template for the plans grid page. Most of the file is not about rendering plan cards at all — renderPlanListContent() (which renders <PlanListContent> containing the actual grid of <PlanCard>s) is a single function call. Everything else in the template is surrounding content: headers, notifications, banners, filters, and — at the very bottom — a fully CMS-driven marketing content zone rendered via <MarketingComponent>.

Page layout, top to bottom

How <MarketingComponent> works

File: src/client/components/molecules/MarketingComponent/MarketingComponent.tsx

<Container paddingLevel={0} appearance='secondary'>
  <MarketingComponent content={contentStore.getPostBodyMarketingContent()} />
</Container>

It receives an array of Contentful entries. For each entry, it reads item.sys.contentType.sys.id — the Contentful content type slug — and dispatches to the matching mapper component:

Any content type not in this map is silently skipped (returns null). This means editors can add new entries in Contentful without a deploy, as long as the content type is already supported here.

Where the array comes from: getPostBodyMarketingContent()

File: src/client/stores/ContentStore/ContentStore.ts

getPostBodyMarketingContent = () => {
  const journeyType = this.simoStore.journeyType
  const segment = this.simoStore.segment

  return this.content.postBodyMarketingContent.filter(({ fields: { tags } }) => {
    const checks = [tags ? tags.includes(MARKETING_SLOT_TAG_NAMES.SLOT_3) : false]
    return shouldShowContentByTag(checks, tags || [], segment, journeyType)
  })
}

this.content.postBodyMarketingContent is populated once, during mapPageContent(), by reading straight off the raw Contentful shop page response:

postBodyMarketingContent: get(
  pageContent,
  `${CONTENTFUL_PATH_CONFIG.basePath}.${CONTENTFUL_PATH_CONFIG.postBodyMarketingContent}`,
  [],
)
// CONTENTFUL_PATH_CONFIG.basePath = 'body.items'
// CONTENTFUL_PATH_CONFIG.postBodyMarketingContent = 'fields.postBodyMarketingContent'
// → reads pageContent.body.items.fields.postBodyMarketingContent

So the CMS field is fetched once for the whole page and holds every marketing entry regardless of journey or segment. getPostBodyMarketingContent() is what filters that raw list down to only the entries relevant to the current visitor, using the tag-matching helper shouldShowContentByTag().

The tag-matching gate: shouldShowContentByTag()

File: src/client/stores/helpers/shouldShowContentByTag/shouldShowContentByTag.ts

const shouldShowContentByTag = (checks, tags, customerSegmentCmsKey, customerJourneyTypeCmsKey) => {
  if (!customerJourneyTypeCmsKey) return false          // no journeyType → never show

  checks.push(tags.includes(customerJourneyTypeCmsKey)) // must match journeyType tag
  if (customerSegmentCmsKey) {
    checks.push(tags.includes(customerSegmentCmsKey))   // must match segment tag too, if provided
  }

  return Boolean(checks.every((c) => !!c))              // ALL checks must be true
}

This is an AND gate. For a marketing entry to appear on the page, its Contentful tags array must contain all three:

• The slot tag — slot3 for post-body content (see MARKETING_SLOT_TAG_NAMES.SLOT_3)
• The current journeyType (e.g. acquisition, upgrade, secondline)
• The current segment (e.g. consumer, business)

Real example from the CMS mock

From __mockapi__/journey/consumer, postBodyMarketingContent currently contains 5 entries:

[
  { contentType: 'iconSnippetList', tags: ['slot3', 'consumer', 'acquisition', 'upgrade', 'secondline'] },
  { contentType: 'contentBlock',    tags: ['consumer', 'acquisition', 'secondline', 'upgrade', 'slot3'] },
  { contentType: 'contentBlock',    tags: ['consumer', 'acquisition', 'secondline', 'upgrade', 'slot3'] },
  { contentType: 'accordion',       tags: ['slot3', 'consumer', 'acquisition', 'secondline', 'upgrade'] },  // ← FAQ
  { contentType: 'accordion',       tags: ['slot3', 'consumer', 'acquisition', 'upgrade', 'secondline'] },  // ← FAQ
]

For a consumer on the acquisition journey, all five tags match (slot3 + consumer + acquisition), so all five render, in array order: icon snippet grid, two content blocks, then two accordions (FAQ sections) at the very bottom of the page.

The FAQ Accordion Below the Plan Grid

File: src/client/stores/helpers/mappers/AccordionMap/index.tsx — rendered via <MarketingComponent>, see above.

The "Frequently asked questions" block visible at the bottom of the plans page is not a bespoke FAQ component. It is a Contentful entry of type accordion inside postBodyMarketingContent, rendered generically by AccordionMap — the same mapper used for any other accordion content anywhere else it might be reused on the page.

Contentful shape

{
  "sys": { "contentType": { "sys": { "id": "accordion" } } },
  "fields": {
    "sectionHeading": "Frequently asked questions",
    "sectionHeadingLevel": 2,
    "theme": "Light",                 // or "Dark" → maps to appearance
    "singleOpen": false,               // true = only one segment open at a time
    "initiallyOpenId": null,           // optionally pre-open one segment by heading text
    "accordionSegments": [
      {
        "fields": {
          "headingText": "What is a SIM only deal?",
          "bodyText": { /* Contentful rich text document */ }
        }
      },
      { "fields": { "headingText": "What's the best place to find cheap SIM only deals?", "bodyText": { ... } } }
      // …15 segments in the current mock
    ],
    "tags": ["slot3", "consumer", "acquisition", "secondline", "upgrade"]
  }
}

Rendering pipeline

AccordionMap source

const AccordionMap = ({ content }) => {
  const { theme, singleOpen, initiallyOpenId, accordionSegments } = content.fields
  if (!accordionSegments.length) return null

  const props = {
    appearance: theme === 'Dark' ? 'secondary' : 'primary',
    multi: !singleOpen || undefined,
    initiallyOpenIds: initiallyOpenId ? [initiallyOpenId] : undefined,
  }

  return (
    <ContentBlockWrapper fields={content.fields}>
      <Accordion {...props}>
        {accordionSegments.map(({ fields: { headingText, bodyText } }, index) => (
          <CollapsibleContainer key={index} id={headingText}>
            <CollapsibleContainerHeader>{headingText}</CollapsibleContainerHeader>
            <CollapsibleContainerBody>
              {bodyText && <ContentfulRichText document={bodyText} />}
            </CollapsibleContainerBody>
          </CollapsibleContainer>
        ))}
      </Accordion>
    </ContentBlockWrapper>
  )
}

Why sectionHeading renders even though AccordionMap doesn't destructure it

AccordionMap passes the entire content.fields object into <ContentBlockWrapper> as a prop, not just the accordion-specific fields it uses itself. ContentBlockWrapper (file: src/client/stores/helpers/mappers/ContentBlockWrapperMap/index.tsx) is a shared wrapper used by several mapper components (ContentBlockMap, AccordionMap, etc). It independently reads sectionHeading, sectionBodyText, and footnote off those same fields:

const shouldRenderSimpleBlockWrapper = ({ sectionHeading, sectionBodyText, footnote }) =>
  !sectionHeading && !sectionBodyText && !footnote

// If any of the three exist, wraps children in a 
// with heading = { text: sectionHeading, level: sectionHeadingLevel }
// Otherwise falls back to a plain  with no heading chrome

Because the FAQ entry has sectionHeading: "Frequently asked questions", it renders the heading via FunctionalContentBlock above the accordion segments — this is why the heading text and the accordion body appear to come from a single component, but are actually two separate concerns (wrapper heading vs. accordion body) reading the same flat fields object.

Multiple FAQ blocks on one page

Because postBodyMarketingContent is an array, there is no restriction on having more than one accordion entry. The current consumer mock has two — likely one for general SIM-only FAQs and one for a more specific topic. MarketingComponent renders every matching entry in the array order returned by Contentful, so editors control ordering entirely from the CMS without a frontend change.

PlanCard Anatomy — The Live BAU Card, Region by Region

This section documents the live, default (non-Highlands, non-CRO) plan card — the one every visitor sees today. It covers PlanCard.tsx and every child it renders, region by region, stating for each piece of visible content whether it is backend-driven, CMS/Contentful-driven, or a local hardcoded constant, plus exactly where in the codebase that value comes from.

Root file: src/client/components/molecules/PlanCard/PlanCard.tsx. Excludes PlanCardEntertainment and PlanCardSimplified (legacy CRO variants — see the CRO section) and the Highlands modal path (see Highlands Overview) — both are alternate rendering paths gated by feature flags, not part of the default card.

Master legend — every numbered region

Region: Ribbon, Badges & Pills

Files: PlanCard.tsx · components/PillAndIconSlot/ · helpers/getPillAndIconSlotProps.ts

Two visually distinct systems produce badges on the card, and they are easy to confuse:

getPillAndIconSlotProps() decision table

Region: Heading, Speed Line & Data Row

Files: helpers/getHeadingInfoSlotProps.ts · PlanCard.tsx (TextStackSlot)

const getHeadingInfoSlotProps = (planNameInfo, commitmentPeriod, showAomPlanTenure) => {
  const formattedCommitmentPeriod = commitmentPeriod?.replace(' Months', '')
  const tenureText = AOM_TENURE_TEXT[formattedCommitmentPeriod] ?? ''
  return {
    heading: { text: planNameInfo?.heading?.name },        // ← backend: plan.planNameInfo.heading.name
    suffix: { text: { suffix: planNameInfo?.suffix } },      // ← backend: plan.planNameInfo.suffix
    ...(showAomPlanTenure && !!tenureText.length && { prefix: tenureText }),  // AOM-only prefix
  }
}

The heading has an optional prefix slot, but it is only populated for AOM (Account On Move / upgrade recommendation) cards when showAomPlanTenure is true, and the text comes from AOM_TENURE_TEXT (constants.ts) — values like "24 month plan". This is the only "prefix" mechanism found in the live heading code, and it does not produce the word "Standard" seen in the reference design.

The Data and Minutes & Texts row uses <TextStackSlot> twice — once fed plan.dataInfo, once fed plan.minInfo. Both objects are entirely constructed by the external @vfuk/utils-shop-plans-card-mapper package from the raw backend plan payload — none of this is Contentful-driven.

Region: Price, Savings & Price Rises

Files: PlanCard.tsx · helpers/formatPriceRises/

// PlanCard.tsx
<TextStackSlot
  primaryTextStack={{
    currency: { symbol: plan?.priceInfo?.unit },
    text: {
      prefix: plan?.priceInfo?.text?.prefix,                 // "Monthly" — from mapper
      main: formatCurrency(plan?.priceInfo?.text?.main, true),// price — from backend monthlyPrice
      suffix: hasSavingsApplied ? plan?.savingsAppliedBanner  // backend override string
                                 : plan?.priceInfo?.text?.suffix, // OR computed "Was £X" from mapper
      suffix2: store.isBusiness && featureFlags.isShowMcpr && MCPR_BUSINESS_VAT_TEXT,
    },
  }}
  secondaryTextStack={{
    priceRiseText: { priceRises: formattedPriceRises },       // from plan.mcpr.priceRise[]
  }}
/>

Region: CTA Button & Lines Dropdown

Files: helpers/PlanCardHelpers.ts (setButtonName) · components/MultipleLinesDropdown/

The CTA button text is entirely local/hardcoded JS logic — there is no CMS involvement. It reacts to journeyType, whether the plan is already selected, and a couple of feature flags:

Business-only: when showLinesDropdown is true, a <MultipleLinesDropdown> renders next to the CTA, letting a business buyer select 1–5 lines. The line count options (range(1, 6)) are hardcoded, and selecting a value recalculates the displayed price client-side (oldPrice / currentLines * selectedLines) before the plan is actually re-fetched from the backend. Not visible on this consumer-segment reference card.

Region: Benefit List Items (Non-Highlands)

Files: CardBenefitsSlot/components/BenefitItems/BenefitItems.tsx · helpers/orderAndEnrichBenefitItems/ · helpers/generateBenefitItemComponents/ · helpers/generateSecureNetBenefitItem/

Every benefit row on the live card goes through the same enrichment pipeline before rendering. This is the BAU path documented in full at Benefit Items Order & Tags — this section focuses specifically on how the pipeline explains the three items pinned above (#12, #15, and the entertainment rows #13/#14 covered in the next section).

Region: Entertainment Image Rows

Files: components/EntertainmentBenefitItem/ · components/EntertainmentImageSlot/

The two rows showing streaming service logos ("Disney+ or Prime") are not built from individual icon components with a text separator. Each is a single pre-composited image asset rendered by <EntertainmentImageSlot>, with its URL supplied entirely by the backend:

// plan.entertainmentPromotion.mediaUrl → passed down through:
PlanCard.tsx: entertainmentImageUrl={plan.entertainmentPromotion?.mediaUrl}
  → CardBenefitsSlot → BenefitItems → generateBenefitItemComponents()
  → EntertainmentBenefitItem → EntertainmentImageSlot
      <Image sm={{ src: entertainmentImageUrl, height: PLAN_ENTERTAINMENT_IMAGE_HEIGHT }} />
// PLAN_ENTERTAINMENT_IMAGE_HEIGHT = '44px' (constants.ts)

Two separate rows appear because two distinct backend product IDs both trigger the entertainment renderer in generateBenefitItemComponents():

If the Phoenix item also has _links['get-contentful'] (and Highlands is off), its heading text is converted into a clickable link via generateBenefitItemWithModal() — this is why "Your choice of entertainment for 24 Months" is underlined, same mechanism as any other CMS-modal benefit.

Region: Footer Link & Footnote

File: PlanCard.tsx (bottom of the component)

{/* <InteractionSlot
  linkWithIcon={{
    text: showHighlandsPlanDetailsModal ? SEE_FULL_PLAN_DETAILS : SEE_PLAN_DETAILS,
    icon: { name: 'arrow-right', justify: 'right' },
    onClick: handleCardInteraction,
    ...
  }}
/> */}

Separately, <CardBuilder footerText={plan?.footerText}> renders backend-supplied legal footnote text (e.g. qualifying line conditions) at the very bottom of the card frame — this is live, just not visible in the reference screenshot.

PlanCardShout — Not Currently Used by the Live Card

File: src/client/components/molecules/PlanCardShout/PlanCardShout.tsx

// PlanCardList.tsx — getPlanCardItem()
if (featureFlagStore.isCroPlanCardEntertainmentEnabled) {
  return (
    <>
      <PlanCardShout promoText={currentPlan?.promoText} ... />
      <PlanCardEntertainment ... />
      ...
    </>
  )
}
return <PlanCard plan={plan} ... />  // ← the live default path never touches PlanCardShout

Promo Cards Injected Into the Plan Grid

File: src/client/components/molecules/PlanListContent/PlanListContent.tsx

Before the grid ever reaches <PlanCardList>, PlanListContent takes the real plans array and splices extra, non-plan items into specific array positions. These placeholder objects don't have plan data — they're just flags (e.g. { loginBanner: true }) that PlanCardList's getPlanCardItem() later detects and swaps for a promo component instead of a <PlanCard>.

The four promo card types

How the splicing works

getFilteredPlans() (a memoized method) runs the raw plans through plansCardMapper(), sorts/reorders them, then splices in placeholder objects at computed array indices:

// PlanListContent.tsx (simplified)
getPlansWithLoginBanner = (plans) => {
  if (trendingPlansEnabled && isTrendingPlansAvailable) {
    return [...plans.slice(0, 6), this.loginBannerProps, ...plans.slice(6)]   // after 6th plan
  }
  if (isCroPlanCardEntertainmentEnabled) {
    // inserted after the 4th non-entertainment plan
    return [...plans.slice(0, indexToPush), this.loginBannerProps, ...plans.slice(indexToPush)]
  }
  return [...plans.slice(0, 4), this.loginBannerProps, ...plans.slice(4)]     // default: after 4th plan
}

// Then separately, a handset/offer banner is spliced at position 4 or 5:
const plansWithBannerPosition = (isCroFilterOptionsEnabled || isCroAomPlansRepositionEnabled || isSeamlessMigration) ? 4 : 5
const plansWithBanner = [
  ...plansWithLoginBanner.slice(0, plansWithBannerPosition),
  this.bannerProps,          // { handsetBanner: true } or { offerBanner: true, offerBannerPlanId }
  ...plansWithLoginBanner.slice(plansWithBannerPosition),
]

Downstream, PlanCardList.tsx's getPlanCardItem() checks currentPlan.loginBanner, currentPlan.handsetBanner, and currentPlan.offerBanner flags (in that priority order, with showFamilyCard checked first) to decide whether to render a promo component instead of the plan at that grid position.

Highlands Feature — Plan Details & Interactive Benefit Modals

Highlands is the internal codename for a complete redesign of the plan card benefits row, plan details page, and interactive modals. It shifts the storefront from a static, hardcoded layout to a fully Contentful CMS-driven architecture where each benefit on a plan card is individually clickable and opens its own rich detail overlay.

Files: src/client/components/molecules/PlanCard/components/Highlands*/ · src/client/components/molecules/CardBenefitsSlot/components/BenefitItems/helpers/mapHighlandsContentfulBenefits/ · src/client/helpers/highlandsBenefitClickCheckGuard/ · src/client/helpers/getHighlandsBenefitName/

Feature Flag Control

Full Component Tree

HighlandsModalContainer is rendered once at the PlanCardList level — not per-card. It observes MobX state and mounts the right modal or tray when a plan or benefit is selected.

PlanCardList.tsx
├── <HighlandsModalContainer />  ← one instance, always mounted when Highlands flag is on
│   ├── Guard: isHighlandsBenefitModalOpen && isHighlandsPhaseOneEnabled && contentStore exists
│   ├── → <HighlandsPlanDetailsModal>  (when a plan has been selected)
│   │   ├── <HighlandsPlanHeader>           "Plan details" heading
│   │   └── <HighlandsPlanDetailsModalBody>
│   │       ├── [View A] <HighlandsPlanDetailsModalContent>   (benefit list — default)
│   │       │   ├── generateBenefitItemComponents()  ← main benefits (visible tag)
│   │       │   ├── generateBenefitItemComponents()  ← modal-only benefits
│   │       │   ├── <HighlandsXtraBenefits>          ← xtra section
│   │       │   └── <HighlandsFaqs>                 ← CMS accordion FAQs
│   │       └── [View B] <HighlandsModalBenefitContentRenderer>  (after clicking a benefit)
│   │           heading · bodyText · heroSnippets · snippets · linksWithIcon · faqs
│   └── → <BottomTray> + <HighlandsModalBenefitContentRenderer>
│         (when selected benefit has tag 'tray' and no plan modal is open)
└── <PlanCard>[]
    └── <CardBenefitsSlot> → <BenefitItems> → generateBenefitItemComponents()

PlanDetailsTemplate.tsx  ← standalone /plan-details URL (deep-link)
└── if (isHighlandsPhaseOneEnabled) → <HighlandsModalContainer isMVAModal />
    else                            → <PlanDetails />  (legacy)

How Highlands Intercepts Legacy Components

The flag split happens in two places:

• Plan card click: PlanCard.tsx → handleCardInteraction()
  • Legacy: calls openPlanListModal() → PlanCardDetailsModal
  • Highlands: calls setHighlandsSelectedPlanId(plan.id) + setIsHighlandsBenefitModalOpen(true) → HighlandsModalContainer re-renders
• Standalone plan-details URL: PlanDetailsTemplate.tsx checks the flag and returns <HighlandsModalContainer isMVAModal /> instead of <PlanDetails />

The Two Contentful Content Systems

This is the most important thing to understand about Highlands. It uses two separate Contentful fetches at two different points in the user journey.

The get-contentful HATEOAS Link — What It Is and Why It Exists

Some inclusiveProducts in the backend plans response carry a _links['get-contentful'] object. This is a HATEOAS pointer telling the frontend that this specific product has rich detail content in Contentful.

{
  "id": "122533",
  "name": "Speed Boost in busy areas",
  "benefitType": "Product",
  "premiumBenefit": true,
  "benefitFeatures": {
    "cmsContentKey": "contentEntryKey=inclusive_product_122533
      &contentType=dynamicJourneyContent
      &spaceName=consumer",
    "isNew": true
  },
  "_links": {
    "get-contentful": {
      "href": "/content-service/v2/content
        ?contentEntryKey=inclusive_product_122533
        &contentType=dynamicJourneyContent
        &spaceName=consumer",
      "type": "GET"
    }
  }
}

{
  "id": "030010",
  "benefitType": "Advertisement",
  "premiumBenefit": true
  // No _links, no benefitFeatures.cmsContentKey
  // Renders as a plain icon+text row — not clickable
}

// Also: basic plan benefit with no extra structure
{
  "id": "2",
  "premiumBenefit": false,
  "planBenefit": "Unlimited minutes & texts"
}

Note on benefitFeatures.cmsContentKey vs _links['get-contentful'].href: Both point to the same Contentful content. cmsContentKey is a query string (e.g. contentEntryKey=inclusive_product_122533&contentType=dynamicJourneyContent). _links['get-contentful'].href is the full proxied URL. In practice the frontend uses cmsContentKey (passed as benefitItem.benefitFeatures.cmsContentKey) when triggering the lazy fetch.

Highlands Data Flow: inclusiveProducts vs. benefitItems

The ID Matching Engine — Backend Product → CMS Entry

mapHighlandsContentfulBenefits() cross-references plan.inclusiveProducts[] (from the backend) against planCardBenefitItemContent.fields.entries (from Contentful) using a numeric ID extracted from the CMS key.

CMS fields used during merge:

• fields.text: Display label. Supports {{commitmentPeriod}} interpolation. Falls back to product.name or product.planBenefit if text is @catalogfallback or empty.
• fields.icon: Split on : → { name, group }. e.g. "globe:system" → name="globe", group="system".
• fields.tags: Array of routing directives (see tag table below).
• fields.benefitFeatures.isNew: If true, benefit is prepended to the list with a "New" pill badge.

Benefit Tag Classification

The Benefit Click Flow — Step by Step

What happens when a user clicks a benefit item in the Highlands plan details modal:

// Parses the query string from cmsContentKey:
// "contentEntryKey=inclusive_product_122533&contentType=dynamicJourneyContent&spaceName=consumer"
const params = new URLSearchParams(href)
const contentEntryKey = params.get('contentEntryKey')  // "inclusive_product_122533"
const contentType     = params.get('contentType')       // "dynamicJourneyContent"

// Calls the content service:
contentServiceV2.getAssetModelV2({ contentEntryKey, contentType })

// Appends to highlandsModalContent with productId prefix for reliable matching:
this.highlandsModalContent = [
  ...this.highlandsModalContent,
  {
    ...dynamicContent,
    fields: {
      ...dynamicContent.fields,
      contentEntryKey: `${productId}_${dynamicContent.fields.contentEntryKey}`,
    },
  },
]

BottomTray vs. Full Modal — When Each Opens

Special / Synthetic Benefit IDs

These are UI-only action items that appear in the Highlands modal but don't correspond to a real numeric inclusiveProduct.id. Because the regex /\d+/g can't extract a number from their contentEntryKey, handleMissingExtractedId() handles them via hardcoded pairs.

SecureNet is also special in that it's injected into the benefit list by processSecureNetBenefit() inside mapHighlandsContentfulBenefits — it appears even if it isn't present in plan.inclusiveProducts, as long as isSecureNetEnabled is true and the CMS entry has a visible tag.

The Joining Engine (Backend ID → CMS Mapping)

A worked example from the __mockapi__/journey/highlands scenario:

// Backend returns (plan.inclusiveProducts):
{ id: "122533", name: "Speed Boost in busy areas", benefitFeatures: { cmsContentKey: "...", isNew: true }, _links: { "get-contentful": { href: "..." } } }
{ id: "030060", benefitType: "Advertisement", _links: { "get-contentful": { href: "..." } } }
{ id: "030010", benefitType: "Advertisement" }          // No _links — not clickable
{ id: "104922", name: "Unlimited Picture Messages" }
{ id: "111068", name: "Inclusive roaming in 84 worldwide destinations" }
{ id: "030260", name: "100% OneNumber Discount", _links: { "get-contentful": { href: "..." } } }
{ id: "2",      planBenefit: "Unlimited minutes & texts" }
{ id: "111871", name: "Uncapped speeds" }

// mapHighlandsContentfulBenefits() cross-references against CMS entries
// whose keys like "benefit_item_122533" → extract "122533" → match product.id
// CMS tags then route each matched item to:
//   mainBenefits      (visible tag) → shown on plan card row + modal
//   modalOnlyBenefits (modalOnly tag) → modal only
//   xtraBenefits      (xtra tag) → HighlandsXtraBenefits section

// Products with no matching CMS entry are silently dropped

The Joining Engine Flow Diagram

Step-by-Step: Adding a New Benefit ID

If the backend adds a new product with ID 777123 that should be clickable in Highlands:

Shared Rendering: generateBenefitItemComponents()

Both the plan card and the Highlands modal use the same rendering function: src/client/components/molecules/CardBenefitsSlot/components/BenefitItems/helpers/generateBenefitItemComponents/generateBenefitItemComponents.tsx

Plan Details — Standard (BAU)

The non-Highlands plan details experience. Highlands is disabled by default — this is what all users see today.

How the modal opens

The user clicks a plan card. handleCardInteraction() in PlanCard.tsx checks the isHighlandsPhaseOneEnabled flag. When false (the default), it calls openPlanListModal({ ...plan, buttonName, buttonState }), which triggers the PlanCardDetailsModal organism.

PlanCardDetailsModal — five tabs

File: src/client/components/organisms/PlanCardDetailsModal/PlanCardDetailsModal.tsx

Data sources for the modal

// PlanCardDetailsModal.tsx
const planSelected = planStore.plans.find(p => p.id === planListModal?.id)
const sharedPlanDetails  = contentStore.content?.planDetailsOverlay  // CMS shared content
const pageSpecificPlanDetails = contentStore.content?.planContent   // CMS per-plan content

PlanDetails standalone page

There is also a dedicated route /sim-only/.../:planId/plan-details that renders PlanDetails.tsx. This page calls store.initPlanDetails(planId), creates a fresh SimoStore, and wraps the same PlanDetailsTemplate. It is used for deep-link sharing of a specific plan's detail view.

PlanCard Anatomy

File: src/client/components/molecules/PlanCard/PlanCard.tsx

PlanCard receives a single plan prop (the transformed backend plan object, shaped by plansCardMapper from @vfuk/utils-shop-plans-card-mapper) plus callbacks and feature flags. It renders a CardBuilder with named slots.

Slot-by-slot breakdown

Complete list of backend plan fields read by PlanCard

plan.id
plan.isSelected
plan.badgeURL                        // Badge icon URL → mapped to icon name
plan.isRecommended
plan.recommendationId
plan.planNameInfo.heading.name       // Plan display name
plan.planNameInfo.suffix
plan.commitmentPeriod                // e.g. "24 Months"
plan.dataInfo.prefix / .main         // e.g. prefix="" main="Unlimited"
plan.minInfo.prefix / .main          // minutes display
plan.priceInfo.unit                  // e.g. "£"
plan.priceInfo.text.prefix           // e.g. "from"
plan.priceInfo.text.main             // e.g. "12.00"
plan.priceInfo.text.suffix           // e.g. "/month"
plan.savingsAppliedBanner            // savings message string
plan.benefitItems.benefitItems[]     // benefit array (non-Highlands)
plan.benefitItems.heading            // benefit section heading
plan.inclusiveProducts[]             // benefit array (Highlands path)
plan.subType                         // e.g. "Unlimited", "Basics Plan"
plan.type                            // e.g. "airtime"
plan.entertainmentPromotion?.mediaUrl // entertainment image URL
plan.mcpr?.priceRise                 // mid-contract price rise flag
plan.reasonMessage[]                 // AOM recommendation reason
plan.footerText                      // legal footer text
plan.promoText                       // promotional label

3onv type variation examples

These are the plan.subType values the frontend currently knows about. A 3onv backend sending a different string will fall through to the essentials fallback in getContentForPlan.

Benefit Items — Order & Enrichment (BAU)

File: src/client/components/molecules/CardBenefitsSlot/components/BenefitItems/helpers/orderAndEnrichBenefitItems/orderAndEnrichBenefitItems.ts

This function is the BAU (non-Highlands) path for benefit items. It takes the raw backend benefit array, enriches each item with CMS content, and returns them in CMS-defined display order.

Function signature

orderAndEnrichBenefitItems(
  planBenefitItemsFromResponse: BenefitItemType[] | undefined,  // from plan.benefitItems.benefitItems
  planBenefitItemsContent:      ContentfulData | undefined,      // from ContentStore CMS data
  commitmentPeriod?:            string,                          // e.g. "24 Months"
  isHighlandsPhaseOneEnabled?:  boolean,                         // flag — false in BAU
)

Step-by-step execution

benefitItemIdsByPriority = ["456", "123"]  // CMS editor ordering

// Backend item: { productId: "123", name: "Roaming" }
// CMS match:   { key: "benefit_item_123", text: "EU Roaming", tags: ["visible"], icon: "globe" }
// Result:      { ...backendItem, heading: { text: "EU Roaming" }, tags: ["visible"], icon: { name: "globe" } }

Concrete example

Backend sends: [{"{ productId: "456", name: "Music" }"}, {"{ productId: "123", name: "Roaming" }"}]

CMS has entries in this order: benefit_item_456, benefit_item_123

// Step 3 → priority list (CMS order):
benefitItemIdsByPriority = ["456", "123"]

// Step 4 → enriched:
[
  { productId: "456", heading: { text: "Spotify Music" }, tags: ["visible"], icon: { name: "music" } },
  { productId: "123", heading: { text: "EU Roaming" }, tags: ["visible"], icon: { name: "globe" } },
]

// Step 5 → sorted by CMS priority (456 first, 123 second):
[
  { productId: "456", ... },  // Music first
  { productId: "123", ... },  // Roaming second
]

// ✅ Display order is controlled entirely by Contentful, not backend order

What happens when a productId has no CMS match

// Backend sends: { productId: "999", name: "Some New Benefit" }
// CMS has no entry: benefit_item_999

// Step 4: benefitItemContent = undefined
//   → no text enrichment, no icon, no tags added
//   → item.heading remains as-is from backend

// Step 5: filterAndSortByPriority checks if "999" is in priority list
//   → "999" NOT in list → item is DROPPED from output
// Result: benefit "999" does not render at all

The role of tags on benefit items

Tags are a string array assigned to each benefit item during the CMS enrichment step (Step 4). They come from Contentful — the CMS editor adds them to each benefit_item_{id} entry. Two constants define what the app recognises:

// BAU — only these two tags are read by the front end:
CMS_BENEFIT_ITEM_VISIBLE_TAG = 'visible'   // item should appear on the plan card
CMS_BENEFIT_ITEM_BOLD_TAG    = 'bold'      // item label should be bold

How tags are used in the BAU (non-Highlands) path

In the BAU path, tags are assigned in Step 4 — item.tags = benefitItemContent?.tags. However, the 'visible' tag is only used for filtering when isHighlandsPhaseOneEnabled is true. In standard BAU mode (flag off), the tag is present on the object but is not used to filter items out. All enriched items that appear in the CMS priority list are shown.

// Inside orderAndEnrichBenefitItems.ts
item.tags = benefitItemContent?.tags   // e.g. ['visible', 'bold']

// Filtering is conditional:
if (isHighlandsPhaseOneEnabled) {
  // Only keep items tagged 'visible'
  filteredBenefits = enrichedBenefits.filter(item => item?.tags?.includes('visible'))
} else {
  // BAU: no tag-based filtering — show all enriched items
  filteredBenefits = enrichedBenefits
}

How tags are used in the Highlands path

File: mapHighlandsContentfulBenefits/mapHighlandsContentfulBenefits.ts
In the Highlands path, tags control where the benefit appears — not just whether it shows. Three tags are recognised:

A benefit item with none of these tags will still be present in the enriched array but will not be rendered in any section.

Entertainment Benefit Icons

Entertainment is a special-case benefit on plan cards. Detection, icon, and image handling all work differently from standard benefit items.

How entertainment is detected

// PlanCard.tsx
const isEntertainmentPlan = plan?.subType?.toLowerCase().includes('entertainment')
// true for subtypes: "UnlimitedEntertainment", "RedEntertainment51", etc.

const isEntertainmentParentPlan = hasRelatedBundles(plan)
// true if the plan has related bundle options to choose from

Entertainment benefit item — ID-based detection

Inside generateBenefitItemComponents.tsx, a benefit item is rendered as an EntertainmentBenefitItem when its productId matches a hardcoded constant:

if (
  benefitItem?.productId === PLAN_BENEFIT_IDS.ENTERTAINMENT_BENEFIT_ID ||
  benefitItem?.productId === PLAN_BENEFIT_IDS.BUNDLED_ENTERTAINMENT_BENEFIT_ID
) {
  return <EntertainmentBenefitItem ... />
}
// All other benefits render as standard BenefitItem

Entertainment image (not icon)

The entertainment image (e.g. a streaming service logo) comes directly from the backend: plan.entertainmentPromotion?.mediaUrl. This is a URL string — no Contentful lookup is involved. The image URL is passed as entertainmentImageUrl to EntertainmentImageSlot and rendered via the Source Web Image component.

Entertainment text in benefit items

The text label for the entertainment benefit comes from CMS (via orderAndEnrichBenefitItems) using the key benefit_item_{ENTERTAINMENT_BENEFIT_ID}. The CMS text may include a {"{{commitmentPeriod}}"} placeholder that is replaced at runtime with e.g. "24 months".

Entertainment plan interaction

When a user clicks "Choose" on an entertainment parent plan, instead of selecting immediately, setSelectedBundledEntertainmentPlan(plan.id) and setEntertainmentTrayOpen(true) are called. This opens a tray for the user to pick their entertainment bundle variant.

Summary: what is hardcoded vs dynamic

Adding a New Plan Type

This is the end-to-end guide for what happens when the backend starts returning a plan.subType the frontend does not know about, and what must change to support it.

Example scenario: backend starts sending plan.subType = "Essentials Plus"

const planSubType = "essentials plus"  // after .toLowerCase()
SUBTYPES["essentials plus"]  // → undefined  (not in constants.ts)

// CMS key constructed:
`devicedetailshandset_${undefined}`.toLowerCase()
// = "devicedetailshandset_undefined"

// findByContentEntryKey() searches for "devicedetailshandset_undefined"
// → no match found → planGroupSpecific = undefined

// Falls through to hardcoded fallback:
findByContentEntryKey(entries, 'packagelistsimo_essentials')
// Shows generic "Essentials" content regardless of the actual plan type

export const SUBTYPES = {
  // ... existing entries ...
  'essentials plus': 'essentialsplus',  // ← add this line
}

'basics plan': 'basicsplan'
// → CMS key: packagelistsimo_basicsplan

Contract Lengths & Commitment Periods

How the frontend handles commitment periods

The frontend has no hardcoded list of valid commitment periods (12, 24, etc.). The backend returns available commitment periods inside journey.filters.commitmentPeriod, and FilterStore uses that array to build the filter UI. Selecting one triggers a new plans fetch with the chosen period as a query parameter.

18-month plans — does it work?

// FilterStore.selectCommitmentPeriod() — generic, works for any period string
selectCommitmentPeriod = async (selectedCommitmentPeriodId: string) => {
  this.selectedCommitmentPeriodId = selectedCommitmentPeriodId  // e.g. '18 Months'
  const updatedState = this.createUpdatedState('commitmentPeriod', selectedCommitmentPeriodId)
  if (updatedState) this.updateFilterStates('commitmentPeriod', updatedState)
  await this.applyFilters()  // → new GET_PLANS request with commitmentPeriod=18+Months
}

The one exception: Basic Upgrade override

This is the only place the frontend actively rewrites a commitment period. When isBasicUpgrade(summary, journeyType) is true, the frontend rewrites the GET_PLANS HATEOAS link before following it:

// simOnlyService.ts
if (isBasicUpgrade(summary, journeyType)) {
  links[HATEOAS_LINKS.GET_PLANS] = {
    ...links[HATEOAS_LINKS.GET_PLANS],
    href: plansLink.href.replace('24+Months', '12+Months'),
    parameters:     { ...plansLink.parameters,     commitmentPeriod: '12 Months' },
    queryParameters:{ ...plansLink.queryParameters, commitmentPeriod: '12 Months' },
  }
}

Comparison: 12-month Basic Upgrade vs standard period selection

Extras / Add-ons Page

ViewStore decision: when is the extras page shown?

File: src/client/stores/ViewStore/ViewStore.ts — goToExtras()

goToExtras = async () => {
  // Gate 1: non-upgrade consumer — skip extras unless flag is on
  if (!featureFlagStore.isAddonsPageEnabled &&
      !(journeyType === JOURNEY_TYPES.UPGRADE || segment === 'business')) {
    return this.goToBasket()
  }

  await contentStore.loadAddonsContent()
  await extraStore.loadExtras()

  // Gate 2: flag off AND no "losing extras" notification → skip
  if (!featureFlagStore.isAddonsPageEnabled && !this.losingExtras) {
    return this.goToBasket()
  }

  this.setPage(PAGE_VIEW.EXTRAS)

  // Gate 3: no actual extras data AND no insurance → skip back to basket
  if (!featureFlagStore.isSimoInsuranceEnabled && extraStore.extrasData.length === 0) {
    this.goToBasket()
  }
}

Who sees the extras page

Required HATEOAS link

// ExtraStore.loadExtras()
if (this.simoStore.links[HATEOAS_LINKS.GET_EXTRAS] === undefined) return
// → If backend does not return a "get-extras" link, loadExtras() exits early
// → extrasData will be empty → Gate 3 will redirect to basket

How to see the extras page for acquisition locally

// In browser console after page load:
window.VFUK.env.FEATURE_FLAGS.showAddonPage = true
// Then navigate — the flag is read from window.VFUK.env at runtime

notifications: [{
  code: 'warning_add-ons-extras-opt-in',
  // ...
}]

Extras page content — what renders

File: src/client/templates/SimoExtrasTemplate/SimoExtrasTemplate.tsx

For a specific brand / journey type — rendering extras for 3onv acquisition

Currently there is no brand concept. The closest parallel is the isBusiness/segment split. To show extras for a 3onv acquisition journey without enabling it for all Vodafone acquisition journeys, the cleanest approach is:

1. Add a brand observable to SimoStore (set from the backend journey response or a query param).
2. In ViewStore.goToExtras(), add: || this.simoStore.brand === 'three' to Gate 1.
3. Pass brand to ContentStore.loadAddonsContent() to fetch a brand-specific CMS block.

Cookie Flow

Cookies serve three purposes in this app: authentication, anonymous session management, and prerender cache control. Here is what each cookie does and when it is read or written.

Key cookies and their roles

How cookies flow through a journey request

Prerender cache and cookies

// prerender.middleware.ts
prerender({
  cookiesToRetain:  ['features', 'customerSegment'],   // Baked into cached HTML
  skipChecker:      (req) => req.cookies.basketId,     // Don't cache if basket active
})

// setCachePolicyForRequest.ts
const hasJourney = req.cookies.basketId
                || req.cookies.JourneyID
                || session.assuranceLevel >= 3

// Only unauthenticated users with no active journey get cached pages
req.readCache  = !hasJourney
req.writeCache = !hasJourney

IDM OAuth2 Login Flow and eShop-auth_p_id_token

Authentication is handled server-side using Vodafone's IDM OAuth2 service via two middleware packages: loginCallbackMiddleware and idmMiddleware from @vfuk/*.

Config: src/server/common/config/idm.config.ts — Middleware: src/server/common/middleware/

getSession.ts — reading the platform session client-side

File: src/client/helpers/getSession/getSession.ts

Despite the eShop-auth_p_id_token cookie being server-side encrypted, the Express server exposes a /session API endpoint that decrypts it and returns the claims as JSON. getSession.ts is a client-side helper that reads this endpoint (or alternatively parses the decrypted value if it has already been server-side rendered into window.VFUK).

The session object returned contains:

interface SessionData {
  assuranceLevel:    number   // 0 = anonymous, 3 = logged in
  platformSessionId: string   // used in API URLs: /api/digital/v1/{platformSessionId}/...
  givenName:         string   // user's first name — shown in header
  numberOfAccounts:  number   // how many Vodafone accounts the user has
  // ... additional claims
}

The platformSessionId is the key value used by runHateoasLink() when constructing API request URLs — it is embedded in the path as a path segment, not a query parameter.

Losing Extras

"Losing extras" is the scenario where a user changes their plan selection and the backend determines that one or more of their previously selected extras (add-ons) can no longer be applied to the new plan. The backend communicates this via notification codes in the plan selection response.

When does this happen?

When the user calls SELECT_PLAN (POST to the HATEOAS selectPlan link) or changes their commitment period, the backend may return a notification[] array containing one or more codes that indicate extras are being lost. These codes are stored in ExtraStore.notifications.

Notification codes that trigger "losing extras"

// ViewStore.ts — LOSING_EXTRAS_NOTIFICATIONS
const LOSING_EXTRAS_NOTIFICATIONS = [
  LOST_SMARTWATCH_BENEFIT,         // 'notification_simo-purchase_existing-smartwatch-removed'
  INSURANCE_AND_EXTRAS_OPT_IN,     // 'notification_simo-purchase_insurance-and-extras-opt-in'
  INSURANCE_OPT_IN,                // 'notification_simo-purchase_insurance-opt-in'
  EXTRAS_OPT_IN,                   // 'notification_simo-purchase_extras-opt-in'
]

The losingExtras getter in ViewStore

File: src/client/stores/ViewStore/ViewStore.ts lines 63–71

get losingExtras(): boolean {
  // Business segment always considered to be "losing extras" — forces extras page
  if (segment === 'business') return true

  // Not applicable if no notifications
  if (!extraStore?.notifications) return false

  // True if ANY notification code matches the losing-extras list
  return extraStore?.notifications.some((el) =>
    LOSING_EXTRAS_NOTIFICATIONS.includes(el.code)
  )
}

What losingExtras = true causes

Business segment special case

3onv consideration

PlanCardEntertainment (CRO — Off by Default)

File: src/client/components/CRO/PlanCardEntertainment/PlanCardEntertainment.tsx
Swap-in point: src/client/components/molecules/PlanCardList/PlanCardList.tsx lines 158–204

How it differs from the standard PlanCard

How the swap works in PlanCardList.tsx

// PlanCardList.tsx lines 158–204 (simplified)
{isCroPlanCardEntertainmentEnabled ? (
  <PlanCardEntertainment
    plan={plan}
    entertainmentPlan={entertainmentPlan}
    isEntertainmentPlanSelected={isEntertainmentPlanSelected}
    showEntertainmentPlan={showEntertainmentPlan}
    toggleEntertainmentPlan={toggleEntertainmentPlan}
    {...sharedProps}
  />
) : (
  <PlanCard
    plan={plan}
    {...sharedProps}
  />
)}

3onv consideration

Since this component is off by default, it does not affect the initial 3onv migration. The standard PlanCard is what needs to be adapted for 3onv content. If the CRO experiment is ever re-enabled, the same entertainment ID hardcoding risks apply (see the Entertainment Icons section).

SimoErrorModal — Global Error Modal Overview

File: src/client/components/molecules/SimoErrorModal/SimoErrorModal.tsx. Mounted once per page, near the root of every top-level page component: Simo.tsx, SeamlessMigration.tsx, P2PMigration.tsx, SimxDetails.tsx, PlanDetails.tsx.

SimoErrorModal is the app's catch-all error surface. It doesn't fetch or own any error data itself — it purely reads SimoStore.error (a single MobX observable) and decides which of four possible UI states to render. Any store, anywhere in the app, can trigger it by calling simoStore.processError(error).

Where the error comes from

// SimoStore.ts
processError = (error: Simo.Error) => {
  console.warn(error)
  const errorCode = error?.data?.errorCode
  this.error = error          // ← setting this is the ONLY trigger for the modal
  this.errorCode = errorCode
}

clearError = () => {
  this.error = null           // ← setting this back to null is the only way to dismiss it
}

processError is called from the catch block of nearly every async store action that talks to the backend: PlanStore (fetch plans, select plan), ExtraStore (toggle extra), FilterStore, ViewStore, MismatchStore, ToggleStore, KeepOrReplaceStore, and NewOrExistingStore. Whatever error object those stores catch — usually the rejected promise from runHateoasLink() — gets passed through mostly unmodified.

The four render states

SimoErrorModal — Every Scenario & Its Error Code

SimoErrorModal — Hardcoded vs. Contentful

The full API_ERRORS map, verbatim:

export const API_ERRORS = {
  cannot_find_device: 'We have not been able to get the details for this device',
  'error-invalid-hateoas-link': 'We have not been able to get the details for this device',
  'error_device-purchase_get-device-variants_failed': 'We have not been able to get the details for this device',
  'error_device-purchase_get-insurance-options_failed': 'We have not been able to get the Insurance products for this device',
  'error_device-purchase_get-plans_failed': 'We have not been able to get the plans for this device',
  'error_device-purchase_get-specifications_failed': 'We have not been able to get the specifications for this device',
  'error_device-purchase_select-insurance-option_failed': 'We have not been able to add this insurance product to your basket',
  'error_device-purchase_select-plan_failed': 'We have not been able to add this plan to your basket',
  'error_simo-purchase_get-plans_failed': 'We have not been able to display the Sim Only plans',
  'error_simo-purchase_select-plan_failed': 'We have not been able to add this Sim Only plan to the basket',
  'warning_simo-purchase_select-plan_max_packages': 'You have reached the maximum number of packages within your bracket, please remove one if you would like to add another',
  'error_simo-purchase-generic-error': 'We are unable to continue this journey at this time. Please reload this page to try again',
  'error_simo-purchase_select-replace-error': 'We have not been able to replace this package at this time, please try again',
  SYS_ERR_DEF: 'We have not been able to get the details for this page',
  'error_simo-purchase_select-extra_failed': 'We have not been able to add this extra to your basket',
  'error_simo-purchase_remove-extra_failed': 'We have been unable to remove this extras from your basket',
}

Note that most of these keys are device-purchase errors (handset journeys), carried over from a shared error-message map — only a handful (simo-purchase prefixed) are actually reachable from the SIM-only plans journey this doc covers.

SimoErrorModal — Gotchas & Shape Mismatches

Two real inconsistencies were found while tracing this component end-to-end. Both are worth knowing about if you're debugging why an error modal shows the wrong text or the wrong button.

// simOnlyService.ts — selectPlan()
const error = { ...err, step: 'selectPlan' }        // ← "step", not "action"

// simOnlyService.ts — selectExtra()
const error = { ...err, reload: false, step: 'selectExtra' }   // ← "step", not "action"

// simOnlyService.ts — removeExtra() follows the same "step" pattern

// KeepOrReplaceStore.ts
this.simoStore.processError({
  errorCode: error.errorCode,
  action: 'keepReplacePackage',   // ← this one really does match
  inline: false,
})

// What SimoErrorModal reads:
const errorCode = get(error?.data, 'errorCode', '')   // looks for error.data.errorCode

// What KeepOrReplaceStore actually sends:
{ errorCode: error.errorCode, action: 'keepReplacePackage', inline: false }   // errorCode is top-level, no .data

SimoBreadcrumbs — Overview

Files: src/client/components/molecules/SimoBreadcrumbs/SimoBreadcrumbs.tsx · src/client/helpers/breadcrumbsBuilder/breadcrumbsBuilder.ts

SimoBreadcrumbs renders the breadcrumb trail above the plan grid (e.g. "Back to plans" / "Upgrades and Offers" / "Add-ons"), plus two things that are easy to miss because they're invisible in the browser: a JSON-LD BreadcrumbList schema for SEO, and — conditionally — the consumer/business <SegmentToggle> switcher.

Guard condition

const breadcrumbContent = get(contentStore, 'content.breadCrumbContent')
if (!(breadcrumbContent && journeyType)) return null

Nothing renders at all — not even the JSON-LD schema — until both a matching Contentful entry exists and journeyType is set. If Contentful is missing the breadcrumb entry for a segment (see Hardcoded vs. Contentful), the whole component silently disappears — no fallback text is shown.

What actually renders — three pieces

<Breadcrumbs
  id='breadcrumbs'
  dataSelectorPrefix={SELECTORS.BREADCRUMBS}
  // items={breadcrumbs}          ← commented out (temporary)
  dataAttributes={{ [TEST_ATTR]: 'simo-breadcrumbs' }}
/>

SimoBreadcrumbs — Link Shape & Build Pipeline

The shape of a single breadcrumb link

// breadcrumbsBuilder.types.ts
export interface IBreadcrumbs {
  id: string      // used as React key + anchor id; lowercased title for CMS-driven items
  text: string     // the visible label
  href: string     // absolute or relative URL
}

Example — a fully built breadcrumb array for a consumer, desktop, acquisition-journey visitor:

[
  { id: 'home',                text: 'Home',                    href: 'https://www.vodafone.co.uk' },        // ← from Contentful
  { id: 'mobile',               text: 'Mobile',                  href: 'https://www.vodafone.co.uk/mobile' }, // ← from Contentful
  { id: 'best-sim-only-deals',  text: 'Our best Sim Only deals',  href: 'https://www.vodafone.co.uk/sim-only/best-sim-only-deals#plans' },
]

How breadcrumbsBuilder() assembles the array

Four independent pieces are concatenated together, in a fixed order. Which pieces actually contribute items depends on device, journey type, and page view:

Where path and title come from — the bold, non-link "current page" crumb

The last item in the trail — the one rendered bold and unclickable because it represents the current page (e.g. "Our best Sim Only deals" in the screenshot above, after "Home" and "SIM only") — is built entirely inside getInitialSimoBreadcrumbs() from two values passed down from SimoBreadcrumbs.tsx:

// SimoBreadcrumbs.tsx
breadcrumbsBuilder({
  ...
  path: isBusiness
    ? 'https://www.vodafone.co.uk/business/business-sim-only#plans'   // ← hardcoded, brand + segment specific
    : 'https://www.vodafone.co.uk/sim-only/best-sim-only-deals#plans', // ← hardcoded, brand + segment specific
  title: get(contentStore, 'content.breadCrumbTitle'),                  // ← this becomes the bold text
})

// breadcrumbsBuilder.ts — getInitialSimoBreadcrumbs()
{
  id: 'best-sim-only-deals',
  text: isMobile ? 'Back to plans' : title,   // ← desktop uses "title" verbatim
  href: `${path}#plans`,
}

path is two literal, fully-qualified vodafone.co.uk URLs baked directly into the component — this is the single biggest brand-awareness blocker in this component (see Brand-Aware Checklist).

title — the actual bold text — comes from content.breadCrumbTitle, set once in ContentStore.ts per segment. Neither branch is Contentful. Traced all the way down:

// ContentStore.ts
// Business:
breadCrumbTitle: 'Business SIM Only',                             // ← hardcoded literal, right here in this repo

// Consumer:
breadCrumbTitle: systemText.getCopy('SIMO_BREADCRUMB_DEFAULT'),   // ← looked up from an npm package, not Contentful

// @vfuk/utils-shop-constants/dist/systemTextResources.js — the actual value:
SIMO_BREADCRUMB_DEFAULT: 'Our best Sim Only deals',

SimoBreadcrumbs — Hardcoded vs. Contentful

How to add or update a breadcrumb link

SimoBreadcrumbs — Brand-Aware Checklist (3onv)

For a Three-branded (3onv) journey to show correct breadcrumbs, every hardcoded vodafone.co.uk reference in this component's pipeline needs a brand-aware equivalent. Here is every single one, in the order a developer would encounter them:

SEO Overview & SimoSeoTags

There is exactly one production component responsible for rendering page-level SEO tags: SimoTemplate/components/SimoSeoTags/SimoSeoTags.tsx. It is mounted once, at the top level, in SimoTemplate.tsx, so every route that renders through SimoTemplate (plans, review, extras, insurance, etc.) inherits it "for free" — none of those nested templates set their own SEO tags. No other template or page imports it.

It wraps the @source-web/head-tags design-system component (HeadTags):

const SimoSeoTags = () => {
  const [seoAsset, setSeoAsset] = useState({})
  const { contentStore } = useContext(SimoContext)
  const { businessContent, consumerContent } = contentStore
  const { pathname } = useLocation()

  useEffect(() => {
    const content = pathname?.includes('business') ? businessContent : consumerContent
    setSeoAsset(get(content, 'seoAsset', {}))
  }, [pathname])

  return (
    <HeadTags
      title={seoAsset.title}
      canonical={seoAsset.canonicalUrl}
      description={seoAsset.description}
      robots={seoAsset.robots}
      ampHtml={seoAsset.ampHtml}
      openGraphType={seoAsset.openGraphType || 'website'}
      openGraphTitle={seoAsset.openGraphTitle}
      openGraphUrl={seoAsset.openGraphUrl}
      openGraphImage={openGraphImage || twitterImage}
      openGraphDescription={seoAsset.openGraphDescription}
      twitterTitle={seoAsset.twitterTitle}
      twitterDescription={seoAsset.twitterDescription}
      twitterImage={twitterImage}
      twitterSite={seoAsset.twitterSite}
      twitterCreator={seoAsset.twitterCreator}
      twitterCard={seoAsset.twitterCard}
      schema={seoAsset.schema?.fields?.schema || []}
    />
  )
}

Every value is 100% CMS-driven — there is no hardcoded copy inside this file. seoAsset comes from ContentStore.ts:

seoAsset: get(pageContent, `${CONTENTFUL_PATH_CONFIG.basePath}.${CONTENTFUL_PATH_CONFIG.pageSeo}.fields`, {})

i.e. pulled straight out of the pageSeo Contentful content-model key (constants.ts, CONTENTFUL_PATH_CONFIG). The only branch in SimoSeoTags is consumer vs. business segment (via pathname.includes('business')) — that is a customer-segment split, not a brand split.

Duplicate/Competing Mechanisms

SEO/head-tag logic is not unified — there are three separate, independent code paths:

There is no shared <Seo>/<Head> wrapper reused across surfaces — each surface implements its own head-tag logic independently, which is why the 404 page has materially weaker SEO coverage than every other route.

Brand-Aware Audit (3onv)

Searching the repo for VFRED, VFT03, a brand resolver, or a BrandStore returns zero live matches. Brand resolution exists as a dependency but is fully disabled:

• package.json lists @vf/utils-brand-resolver as a dependency — but it is not imported anywhere in src.
• src/server/common/config/clientDynamicEnvVariables.config.ts is the only file that ever referenced it, and every line is commented out:

  // import { resolveBrandId } from '@vf/utils-brand-resolver'
  // const brandId = resolveBrandId(req)
  // console.log(`Brand ID ✅: ${brandId}`)

  brandId is never computed, never attached to res.locals or the client env payload, and never reaches SimoSeoTags or ContentStore.

Conclusion: there is no brand-conditional logic anywhere in the SEO path. At the component level, SimoSeoTags.tsx has zero hardcoded brand strings — every SEO field (title/description/canonical/OG/Twitter/schema) passes straight through whatever Contentful returns, so in isolation the component itself is not "hardcoded to Vodafone". The risk is architectural: the rest of the app around it is single-brand throughout, so if a 3onv (Three) journey ever reused this exact deployment without a brand-scoped Contentful space, the SEO tags themselves might vary by CMS content, but surrounding on-page links would still leak Vodafone URLs. Same class of finding as the Breadcrumbs Brand-Aware Checklist:

Gaps & Dead Code

• parseSchemaObject.ts is dead/unwired. src/client/helpers/parseSchemaObject/parseSchemaObject.ts recursively rewrites context/type keys to @context/@type for JSON-LD, but it is not imported by SimoSeoTags.tsx or any other production file — seoAsset.schema is passed to HeadTags raw, presumably already correctly keyed by Contentful. Its only consumer is its own test file, whose mock fixtures hardcode Vodafone social URLs (facebook.com/vodafoneUK, twitter.com/vodafoneuk, youtube.com/user/VODAFONEUK) — test data only, not shipped.
• No hreflang / htmlLang / organisationSchema. Supported by the underlying HeadTags component but never passed from SimoSeoTags — see SEO Overview.
• 404 page has minimal SEO coverage. NotFound.tsx uses a separate library (react-helmet) and sets only a prerender-status meta tag — no title/description/OG/Twitter/schema. See Duplicate/Competing Mechanisms.
• Two independent robots controls. Page-level CMS seoAsset.robots (per SimoSeoTags) vs. the static site-wide robots string in core.config.ts — these could disagree and no code ties them together.

Prerender

The app uses @vfuk/lib-web-prerender to serve cached, server-side rendered HTML to unauthenticated visitors. This avoids the cost of React hydration for every anonymous page load and improves Core Web Vitals / SEO.

How it works at a high level

// prerender.middleware.ts
const redisClient = process.env.PRERENDER_SERVICE_URL
  ? new Redis(process.env.PRERENDER_SERVICE_URL)
  : new MockRedis()

// prerender.middleware.ts
skipChecker: (req) => req.cookies.basketId

The window._isPrerender flag

File: src/client/index.tsx

When the prerender bot is rendering the page, it sets a global flag on the window object before React boots. The React bootstrap code reads this:

// src/client/index.tsx
const isPrerender = window._isPrerender === true

// Different root creation based on context:
if (rootElement.hasChildNodes()) {
  // SSR/prerender has already put HTML in the DOM — hydrate it
  hydrateRoot(rootElement, <App />)
} else {
  // Fresh browser render — create a new root
  createRoot(rootElement).render(<App />)
}

CSS injection during prerender

CSS-in-JS (styled-components) normally injects styles via the CSSOM API, which is invisible to the prerender bot's HTML snapshot. To ensure styles are captured in the static HTML:

// src/client/index.tsx
<StyleSheetManager disableCSSOMInjection={isPrerender}>
  <App />
</StyleSheetManager>

// When isPrerender is true:
//   → styles injected as <style> tags in the HTML (visible to snapshot)
// When isPrerender is false:
//   → styles use faster CSSOM API (standard browser behaviour)

Cookies retained in cached HTML

// prerender.middleware.ts
cookiesToRetain: ['features', 'customerSegment']
// These two cookies are baked into the cached HTML so that the correct
// segment variant (consumer/business) and feature flags are preserved
// in the cached snapshot.

Summary table

3onv consideration

makeAPIRequest / runHateoasLink()

File: src/client/services/simOnlyService/helpers/makeAPIRequest/makeAPIRequest.ts

All backend API calls in this app flow through a single function: runHateoasLink(). It is the gateway between the MobX stores and the backend. It handles URL construction, HTTP method overrides, authentication headers, and special HATEOAS response actions.

Flow diagram

URL construction in detail

// Backend HATEOAS link href comes in two forms:
// v1: "/simo/v1/journey/abc123/plans"
// v2: "/simo/v2/journey/abc123/plans"

// runHateoasLink detects the version and prepends the correct proxy path:
const prefix = href.includes('/v2/') ? '/api/digital/v2' : '/api/digital/v1'
const fullUrl = `${prefix}${href}`
// → "/api/digital/v1/simo/v1/journey/abc123/plans"
// The Express /api proxy middleware strips the prefix and forwards to DXL

patchHateoasLinkWithQueryParam()

A utility function used before calling runHateoasLink() when a query parameter needs to be appended to a HATEOAS href. For example, the commitment period override for basic upgrades uses this to replace the commitment_period query param in the GET_PLANS href before the plans call is made.

// Usage pattern:
const modifiedLink = patchHateoasLinkWithQueryParam(
  originalLink,
  'commitment_period',
  '12+Months'
)
await runHateoasLink(modifiedLink, 'GET')

HTTP methods handled

PATCH and DELETE are sent as POST because some proxy layers and CDN configurations block non-standard HTTP methods. The backend reads the override header and treats the request as a PATCH or DELETE accordingly.

Special HATEOAS response handling

// After receiving a response, runHateoasLink checks _links:
if (response._links?.['sign-in']) {
  // Session has expired or user needs to authenticate
  // → redirect to IDM login flow via /web-shop/login
  window.location.href = '/web-shop/login'
  return
}

if (response._links?.['go-to-basket']) {
  // Plan selection is complete and the backend wants to move to checkout
  // → redirect to the basket/checkout URL from the link
  window.location.href = response._links['go-to-basket'].href
  return
}

// Otherwise: return response data to the calling store

3onv consideration

Mismatch Codes

When the backend detects a conflict between the user's login state and their basket contents (e.g. logged in as a consumer but shopping as a business, or session expired with items in basket), it returns one or more notification objects in the API response. The frontend intercepts these and shows a modal with contextual messaging and action buttons.

getMismatchCodes() — the detection function

File: src/client/helpers/getMismatchCodes/getMismatchCodes.ts

const getMismatchCodes = (response: Object = {}): string => {
  // 1. Extract the notification array from the response
  const notificationArray = get(response, 'notification', [])

  // 2. Find the FIRST notification code that exists in MISMATCH_STATUS_CODES
  const notification = notificationArray.find((singleNotification) => {
    return !!MISMATCH_STATUS_CODES[singleNotification.code]
  })

  // 3. Return the code string (or undefined if none matched)
  return notification && notification.code
}

Only the first matching code is returned. If the backend sends multiple mismatch notifications, only the first one that has a corresponding entry in MISMATCH_STATUS_CODES is acted on.

How the modal is triggered

Complete mismatch code reference

File: src/client/constants/mismatchStatusCodes.ts

Handler function reference