web-shop-data-simo

Vodafone UK · Data SIM Only (SIMO) e-commerce journey · Consumer & Business segments

This is the front-facing web application that powers Vodafone's Data-SIM-Only (SIMO — SIM Only, data variant) purchase journey. It lets customers and business users browse data plans, pick add-ons, and complete checkout for a SIM card that provides mobile data with no voice calls included. The app supports both brand-new customers (acquisition) and existing Vodafone subscribers upgrading or migrating their tariff.

Guided Tour — Start Here

If you're new to this repo, read these sections in order. Each one builds on the last.

Who Are You?

Jump straight to what you need most.

Tech Stack

TL;DR: React 17 with TypeScript on the frontend, Express.js for server-side rendering, MobX for state, Vite for bundling, Contentful for content, and a suite of Vodafone-internal (@vfuk) and Vodafone design system (@source-web) packages.

Notable Internal Packages

Architecture Diagram

TL;DR: The browser talks to an Express server, which proxies API calls through DXL (the Vodafone API gateway) to backend microservices. Content is fetched from Contentful. All routing back to services uses AWS API Gateway.

Walking Through the Diagram

1. ① Page request — A user visits /data-only-sim. Their browser sends an HTTP GET to the Express server.
2. ② Render HTML — The Express server renders React to HTML server-side (SSR), returning a fully-formed page to the browser. This makes the first paint fast and SEO-friendly.
3. ③ API calls — Once the browser loads the JavaScript bundle, React hydrates and the purchase journey begins making API calls as the user interacts (selecting a plan, adding extras, etc.).
4. ④ Authenticated request — All API calls go through the DXL Proxy middleware, which attaches authentication headers (session token, API key) before forwarding to AWS API Gateway.
5. ⑤ Purchase APIs — AWS Gateway routes to either the new SIMO-Purchase service (v2) or the legacy Data-SIMO-Purchase service (v1) depending on the journey type and feature flags.
6. ⑥ Auth — The Auth Service (IDM — Identity Management) handles login, session validation, and two-factor authentication (2FA).
7. ⑦ Content — The Content Service fetches marketing copy, plan descriptions, and signposting text from Contentful, transforming it into a format the frontend can render directly.

Purchase Journey — Request Flow

TL;DR: A purchase journey is a server-managed state machine. The frontend creates a journey, fetches available plans, the user selects one, extras are optionally added, and the journey concludes. State transitions are driven by HATEOAS links (see HATEOAS section) not hardcoded URLs.

Journey State Transitions

The journey progresses through these states. Each state is driven by an action call to the backend:

Server-Side Rendering (SSR)

TL;DR: The Express server renders the initial React tree to HTML on first load. After that, the browser takes over and React updates the page dynamically without full reloads.

• Entry point: src/server/production/server.ts — Express application with middleware pipeline
• The server mounts at path prefix /data-only-sim
• A dedicated pre-render service is also referenced for crawler/SEO pre-rendering
• MobX stores are hydrated server-side with initial data, then serialised into the HTML and re-used client-side to avoid double-fetching
• Vite handles the build in both SSR mode (for the server bundle) and client mode (for the browser bundle)

Key Server Entry Points

CMS — Contentful Integration

TL;DR: Yes — this app is heavily CMS-driven. Almost all user-visible text, images, signposting panels, and marketing content is fetched from Contentful (a headless CMS). The app never hardcodes product copy directly in React components.

Contentful Dependencies

• @contentful/rich-text-html-renderer v16.6.10 — converts Contentful rich-text JSON to HTML
• @contentful/rich-text-types v16.8.5 — TypeScript types for Contentful document nodes
• @source-web/contentful-rich-text v11.5.2 — Vodafone design-system wrapper for rendering rich text
• @vfuk/utils-middleware-content-api-transformer v2.0.3 — Express middleware that transforms Contentful API responses into a consistent shape

Content API Endpoint

GET /api/content-service/v2/content
    ?contentEntryKey=dataonlysim_consumer
    &contentType=marketingContent
    &spaceName=consumer

The contentEntryKey identifies the specific Contentful entry. The spaceName is either consumer or business, selecting the correct Contentful space.

Contentful Content Keys

The following keys are used to fetch content entries. Each key maps to a Contentful entry that an editor manages:

Contentful Layer Types

Content is organised into layers. Each layer type controls a different region of the page:

Content Store

Fetched Contentful content is stored in the MobX DataSimoContentStore. This store holds all CMS content for the current page session and makes it available to any component that needs it.

Content Key → Component Mapping

TL;DR: Every content key ends up on screen somewhere inside the DataSimoTemplate tree (or a store/helper it feeds). Some keys have a dedicated store getter; others are queried ad hoc by the component that needs them.

Backend Endpoints

TL;DR: The app calls four distinct backend service groups — Content, SIMO-Purchase (new), Data-SIMO-Purchase (legacy), and Auth/Authorization. All calls are proxied through the DXL proxy, which adds authentication headers and routes to AWS API Gateway.

HATEOAS Navigation

TL;DR: HATEOAS (Hypermedia As The Engine Of Application State) means the backend tells the frontend what actions are available at each step. The frontend never hardcodes "what to call next" — it reads the links from the last API response and follows them.

How it works in code

Each API response from the purchase service includes a links array. Each link has a rel (relation type) that tells the frontend what that link means. The frontend extracts the link by its rel and calls it to progress the journey.

// Example API response structure
{
  "journeyId": "abc-123",
  "status": "PLAN_SELECTED",
  "links": [
    { "rel": "get-extras",    "href": "/simo-purchase/.../plans/xyz/extras", "method": "GET" },
    { "rel": "empty-basket",  "href": "/simo-purchase/.../empty-basket",      "method": "GET" },
    { "rel": "get-subscription-summary", "href": "/simo-purchase/.../subscription-summary", "method": "GET" }
  ]
}

The frontend looks up the link by rel and calls the href — it never constructs these URLs itself.

HATEOAS Link Reference

State Management — MobX

TL;DR: All application state is managed with MobX 6. Stores hold journey state, plan selections, content data, auth state, and UI state. Components observe stores and re-render automatically when state changes.

Key Stores

MobX Pattern Used

The codebase uses MobX with mobx-react (the React bindings). Components are wrapped with observer() to make them reactive to store changes. Stores use makeAutoObservable or makeObservable for declaring which properties are observable.

// Typical pattern — component reacts to store changes automatically
import { observer } from 'mobx-react'

const PlanSelector = observer(({ store }) => {
  // Re-renders whenever store.selectedPlan changes
  return <div>{store.selectedPlan?.name}</div>
})

Store Access Pattern

Stores are typically injected via React Context or passed as props from the top-level page component. There is no global singleton store — stores are created per-request on the server side to avoid state leaking between users.

Auth & Identity

TL;DR: Authentication is handled by IDM (Identity Management) — a Vodafone internal service. The frontend uses middleware packages (@vfuk/web-middleware-idm, @vfuk/web-middleware-login-redirect) to validate sessions and redirect unauthenticated users.

Auth Flow

1. User lands on the purchase page
2. The @vfuk/web-middleware-idm middleware checks for a valid session cookie
3. If no valid session: @vfuk/web-middleware-login-redirect redirects to the Vodafone login page
4. After login, IDM issues a session token (stored in a cookie)
5. All subsequent API calls are made with this token in the headers (added by the DXL proxy)
6. For high-security actions, a 2FA (Two-Factor Authentication) challenge is triggered via POST /auth/2fa/actions/sendOtp

Auth Endpoints Summary

Key Auth Middleware Packages

Routing

TL;DR: React Router 5 manages client-side navigation. The app has two base paths — /data-only-sim for consumer and /business/data-only-sim for business. Routes are defined in src/client/routes.tsx.

The server is mounted at the path prefix /data-only-sim. The channel ID used in API calls is eShop-data-simo.

Plan Filtering & Sorting

TL;DR: The data model (FilterStore) supports six filter dimensions and the API supports a sortBy parameter, but only one filter — commitment period (contract length) — actually has a UI control. Everything else is defined in the types and analytics config but has no rendered control anywhere in the app today.

Filter dimensions defined in IFilters

FilterStore.types.ts defines the full shape of filters the backend journey response can carry:

Sorting — sortBy

TL;DR: Sorting is not a UI control either. It only works as a deep-link query parameter — if a URL like ?sortBy=monthlyPrice.asc is used to land on the page, the value is forwarded to the backend's HATEOAS link query parameters. There is no on-page sort dropdown.

// src/client/services/dataSimOnlyService/helpers/deeplinkingQueryOverride/deeplinkingQueryOverride.ts
if (paramKey === 'sortBy') {
  const isDefault = ['default', 'recommended'].includes(deepLinkQueryParams[paramKey])
  hateoasLink.queryParameters[paramKey] = isDefault ? '' : deepLinkQueryParams[paramKey]
}

Any sortBy value present in the page's URL query string is copied onto the outgoing HATEOAS link before it's called — default and recommended are normalised to an empty string (the backend's default ordering).

Module & Component Inventory

TL;DR: The app is split into client-side React components/pages, server-side Express middleware, shared services, and MobX stores. Most UI components come from the @source-web design system.

Getting Started

TL;DR: Clone, install with npm, set up your .env file, and run npm run dev. You'll need Node.js and access to the Vodafone internal npm registry for @vfuk and @source-web packages.

Prerequisites

• Node.js (check .nvmrc or package.json engines for the required version)
• npm (comes with Node)
• VPN / internal network access for Vodafone npm registry
• Access to an environment's backend services (or a local mock)

Install & Run

# Install dependencies (requires VPN + Vodafone registry credentials)
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Start production server (after build)
npm start

Testing

# Run unit tests (Jest + Enzyme)
npm test

# Run tests in watch mode
npm run test:watch

# Run E2E tests (Cypress)
npm run cypress:open    # Interactive browser mode
npm run cypress:run     # Headless CI mode

Linting & Type Checking

# ESLint
npm run lint

# TypeScript type check (no emit)
npm run type-check

# Stylelint (CSS/SCSS)
npm run stylelint

Local Environment Setup

Copy the appropriate .env/ file for your target environment. For local development against a real environment, use .env/local-prod.env or .env/int1.env and ensure your AWS_GATEWAY_DAL_URL and AWS_GATEWAY_DAL_API_KEY are set.

Feature Flags

TL;DR: Feature flags are managed via Launch Darkly, accessed through the @vfuk/lib-web-feature-flagging package. Flags gate features behind toggles that can be turned on or off per environment without a code deploy.

Feature flags are particularly relevant to controlling which purchase API version is used — the v1 legacy service vs. v2 SIMO-Purchase service. Before changing any flow, check whether it's gated behind a feature flag.

Observability & Logging

TL;DR: Logs go to Datadog via @vfuk/lib-web-fe-logger. Real-user monitoring (RUM) runs via Datadog RUM. Analytics events go to Tealium.

Health Check Endpoints

Both backend services expose health endpoints. These are used by load balancers and monitoring systems to check if the service is alive:

• GET /simo-purchase/actuator/health — basic health check
• GET /simo-purchase/actuator/vhealth — extended health including dependency status
• GET /data-simo-purchase/actuator/health — basic health check (legacy service)
• GET /data-simo-purchase/actuator/vhealth — extended health (legacy service)

Testing

TL;DR: Unit tests use Jest + Enzyme. End-to-end tests use Cypress 10. SonarQube provides static analysis in CI/CD.

Gotchas & Traps

Non-obvious behaviours and known limitations. Read before shipping.