HomeTest Service

The HomeTest Service is a service that provides a central hub for ordering home tests for NHS patients.

This repository contains the full stack, including the frontend, backend lambdas, and infrastructure-as-code.

Table of Contents

• HomeTest Service
  • Table of Contents
  • Setup
    • Prerequisites
      • mise
      • Local Secrets
  • Usage
    • Local Development
    • Common local workflows
    • Frontend
    • Local Infrastructure
  • Testing
  • Design
    • Architecture
  • Contributing
  • Licence

Setup

1. Clone the repository

   git clone https://github.com/NHSDigital/hometest-service.git
   cd hometest-service

2. Install mise (recommended package manager)

   curl https://mise.run | sh
   echo 'eval "$(mise activate zsh)"' >> ~/.zshrc  # or ~/.bashrc for bash
   source ~/.zshrc

3. Install project dependencies using mise

   mise install  # Installs Node.js and Terraform versions from .mise.toml

4. Install dependencies for the root, lambdas, and tests, start the local development environment

   pnpm install
   pnpm run start

Prerequisites

The following software packages, or their equivalents, are expected to be installed and configured:

• Docker
• Node v24 LTS,
• A tool version manager:
  • nvm version manager. This repository contains a .nvmrc file, to make the runtime version consistent.
  • mise (reads .mise.toml)
• Terraform. The version is specified in [.tool-versions].
  • Local development uses Terraform to deploy to LocalStack.

mise

Mise can read the .nvmrc file by following the instructions.

Important commands:

pre-commit install # Enables the git hook to run the checks locally on commit
mise run pre-commit   # Run the pre-commit task defined in .mise.toml

Local Secrets

Before starting, ensure the following files are present in local-environment/infra/resources/secrets/.

Warning

These files contain sensitive credentials. They must never be committed to git or shared in plaintext. Obtain them only through a team-approved secure channel.

• nhs-login-private-key.pem — NHS Login private key
• os-places-creds.json — OS Places API credentials

Usage

Local Development

To spin up the entire local environment (LocalStack, Postgres, and the Next.js Frontend):

pnpm start

This command:

1. Starts the Docker containers defined in local-environment/docker-compose.yml.
2. Bootstraps LocalStack via Terraform, and deploys the lambdas to it from the /lambdas directory.
3. Starts the frontend on http://localhost:3000.

To stop the environment:

pnpm run stop

Common local workflows

After running pnpm start, use targeted commands instead of restarting everything:

• Lambda code changes (build/package/deploy lambdas to LocalStack):

  pnpm run local:deploy

• Database schema or seed changes (rerun DB migration container, including goose migrations):

  pnpm run local:service:db:migrate

• Terraform infrastructure changes (apply infra updates to LocalStack without restarting containers):

  pnpm run local:terraform:apply

  This expects the backend containers, including LocalStack, to already be running. If they are not, start them first:

  pnpm run local:backend:start

  To switch local integrations between WireMock and real upstreams, pass Terraform variables when applying - some examples below.

  To only use WireMock everywhere (default mode - only needed to switch over):

  TF_VAR_local_service_mode=wiremock pnpm run local:terraform:apply # this is the default mode, only needed to switch over

  To not use WireMock anywhere (real downstream APIs):

  TF_VAR_local_service_mode=real pnpm run local:terraform:apply

  To use WireMock except for specific services, pass only the overrides you need:

  TF_VAR_local_service_mode=wiremock \
  TF_VAR_local_supplier_service_url_override=https://supplier.example.com \
  TF_VAR_local_use_ui_auth_url_override=https://auth.sandpit.signin.nhs.uk \
  TF_VAR_local_postcode_lookup_base_url_override=https://api.os.uk/search/places/v1 \
  pnpm run local:terraform:apply # pnpm run local:frontend:restart - if overriding UI auth

  If you change UI-facing auth settings, restart the frontend so it picks up the updated ui/.env.local values:

  pnpm run local:frontend:restart

• Restart backend containers only (Postgres, LocalStack, WireMock, db-migrate):

  pnpm run local:compose -- stop postgres-db localstack wiremock
  pnpm run local:backend:start

• Restart frontend only:

  pnpm run local:frontend:restart

• Start/stop backend only:

  pnpm run local:backend:start
  pnpm run local:compose -- stop postgres-db localstack wiremock

• Start/stop frontend only:

  pnpm run local:frontend:start
  pnpm run local:compose -- stop ui

• Start/stop specified lambda

  LAMBDA={lambda_name} pnpm run local:service:lambda:enable
  LAMBDA={lambda_name} pnpm run local:service:lambda:disable

Frontend

The frontend is located in the /ui directory. It is a React Router SPA built with Next.js as a static-export shell — not a standard Next.js application.

1. cd to /ui directory.
2. Run pnpm install.
3. Run pnpm run dev.

• When creating a new page, use the PageLayout component found in /ui/src/components.
• To create a new route, create a directory with the name of your route in /ui/src/app, and add a page.tsx file within.
• All route/page components live under ui/src/routes/ and are registered in ui/src/app.tsx (the React Router config).
• Layout components live under ui/src/layouts/. Use these (e.g. FormPageLayout, JourneyLayout) when building new pages.
• Use components from nhsuk-react-components for standard NHS UI elements; use Tailwind utility classes for custom spacing and layout.
• Never use next/link, next/navigation, or Next.js API routes — all navigation goes through React Router and all backend logic lives in Lambda functions.

Local Infrastructure

Local infrastructure is managed via Terraform in the /local-environment/infra directory.

Testing

We use Playwright for end-to-end testing, located in the /tests directory.

Design

Architecture

The service follows a serverless-first architecture on AWS:

• Frontend: Next.js (React)
• Backend: AWS Lambda (Node.js/TypeScript)
• Database: PostgreSQL (managed via Docker locally)
• Infrastructure: Terraform

System diagrams and design documents can be found in the /docs and /architecture folders.

Contributing

View the contributing guidelines.

Licence

The LICENCE.md file will need to be updated with the correct year and owner

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

Any HTML or Markdown documentation is © Crown Copyright and available under the terms of the Open Government Licence v3.0.