PETS (Pre-Entry TB Screening)

Overview

An electronic data capture system designed to address inconsistencies and fraud issues in the current Tuberculosis screening process. For a deepdive into the process, check out the UK Tuberculosis Technical Instructions.

Built With

Architecture

See docs/architecture/README.md for a full system overview and component diagram. The original architecture diagram is also available as docs/architecture.pdf.

Documentation

Topic	Link
Getting started (new developers)	docs/GETTING-STARTED.md
Architecture overview	docs/architecture/README.md
Backend services (all 7)	docs/backend-services/README.md
API endpoint reference	docs/api-reference/README.md
Database schema & migrations	docs/database/schema.md
Deployment guide	docs/deployment/README.md
Operational runbooks	docs/operations/runbooks.md
Security guide	docs/operations/security.md
Troubleshooting	docs/troubleshooting.md
Contributing guidelines	CONTRIBUTING.md
AWS access	docs/aws-access.md
LocalStack configuration	Localstack_config.md

Monorepo Organization

📦pets-ui      # Frontend UI Root
 ┣ 📂cypress   # End to End Tests
 ┣ 📂src       # Source Code
 ┣ 📂test      # Integration Tests

 📦pets-core-services/src         # Core Services for the Backend
 ┣ 📂applicant-service            # Everything pertaining to Applicant
    ┣ 📂lambdas                   # Lambda code for Applicant service lambda
 ┣ 📂application-service          # Everything Application-related
    ┣ 📂lambdas                   # Lambda code for Application service lambda
 ┣ 📂clinic-service               # Everything Clinic-related
    ┣ 📂lambdas                   # Lambda code for Clinic service lambda
 ┣ dicom-service                  # Everything dicom-related
    ┣ 📂lambdas                   # Lambda code for dicom service to check for malware
 ┣ EDAP-integration-service       # Everything related to EDAP integration
    ┣ 📂lambdas                   # Lambda code for EDAP integration service lambda
 ┣ Audit-service                  # Everything related to Audit
    ┣ 📂lambdas                   # Lambda code for Audit service lambda
 ┣ 📂lambda-authoriser            # Authentication Service
    ┣ 📂lambdas                   # Lambda code for Authoriser lambda


 📦pets-local-infra             # Definition of lambdas, dynamodb, apigateway etc needed to emulate AWS services for local development
 ┣ 📜lib/local-infra-stack.ts   # Local aws services definition

 📦Config                     # Project Configs
 ┣ 📜.env                     # configs for local environment
 ┣ 📜.env.local.secrets       # environment secrets for local environment, generated when you run `pnpm pull:secrets`. Please don't commit 🙅🏽!
 ┣ 📜.env.dev                 # configs for a Dev deployment
 ┣ 📜.env.test                # configs for a Test deployment
 ┣ 📜.env.test.local          # configs for unit and integration tests

Additional configs specific to a core service are defined in their directory

Getting Started

For a comprehensive step-by-step setup guide, see docs/GETTING-STARTED.md. For common setup problems, see docs/troubleshooting.md.

Supported Platforms

• Mac
• Linux
• Windows 10 or Windows 11(64-bits)

Prerequisites

• Node 20

  • volta installation guide

  • Install Node 20

    volta install node@20

  • Verify Node Version with node -v, should return v20.19.0

• Pnpm

  npm install -g pnpm@9.15.4

• Docker

  • Check if Docker is installed.

     docker -v

  If Docker is installed, this command will return the installed Docker Engine version. If it is already installed, you can skip the next steps.

  • Install Docker via Docker Desktop using the installation guide. (Please note this is blocked on Accenture laptops)

  • Alternatively, install Rancher Desktop.

    • Download from homepage and install.

    • Verify docker installation

         docker -v

    • Make any necessary configuration changes for localstack.

• Git Secrets

  • Install
    • Linux: apt-get install git-secrets
    • Mac: brew install git-secrets
    • Windows:
      1. Ensure git is configured in your windows OS
      2. Clone awslabs/git-secrets repo by executing git clone https://github.com/awslabs/git-secrets.git in Git Bash
      3. Open Powershell and 'run as administrator' and go to the path where the repo is cloned - e.g. C:\user\...\ttn\git-secrets
      4. Execute the installation script by executing ./install.ps1
      5. Now that you have git secrets in your windows OS, go cd to the project repo and execute git secrets --install to add a git secrets hook to the local repository

Installation

1. Clone the repo

   git clone git@github.com:UKHSA-Internal/pre-entry-tb-screening-app.git
   cd pre-entry-tb-screening-app

2. Install project dependencies

   pnpm i

   This would pull Node dependencies for frontend and core services.

3. Install recommended VsCode extensions present in .vscode/extensions.json

   This would install recommended extensions for linting and formatting.

4. Configure Git Secrets

     git secrets --install
     git secrets --register-aws

5. Configure End of Line

   • Open the User Settings from the Command Palette and search for "end of line"

   • Ensure "Prettier: End Of Line" is set to "lf"

   • Ensure "Files: Eol" is set to "\n"

   • Run the following:

      git config --global core.autocrlf input

Pulling Secrets for local development

Skip this section if you are not running E2E tests on your machine. As a prerequisite, please ensure you have administrator access to the pre-entry-tb-screening-nl-develop account.

1. Navigate to Halo page.

2. Select Administrator Access Keys for pre-entry-tb-screening-nl-develop account.

3. Copy the commands under option to Set AWS environment Variables. Be sure to check the OS tab is set correctly beforehand.

4. Open a new shell and run the commands.

5. Pull the secrets with the commands below:

   pnpm pull:secrets

6. Verify .env.local.secrets has been created in configs directory. Double check this file is not committed.

Development Processes

All captured here

Ticket Creation

User story and bug tickets should follow this template.

Picking up Tickets

• When starting work on a new ticket, open a new branch using the following naming convention: feature/{ticket-number}-{concise-description}. For example: feature/TBBETA-123-setup-auth.

• Commits should be done regularly and commit messages should be meaningful. Commit messages should follow this convention - {ticket-number}: {commit_message}. For example: TBBETA-123: Added unit tests

• Ensure your commit email is your ukhsa email. Check this SO thread on how to change that.

Running Development Environment

1. Start up development environment

   pnpm start

   Please ensure Docker is running before you run this command. Please note this would take a bit of time(roughly 45 seconds)

2. Navigate to the React app on http://localhost:3000/

See individual folder READMEs for more information

Alternatively, for slow PCs, you can start only the UI without the backend with this command pnpm start:ui.

IMPORTANT!!! To be able to use localstack (to run back-end), you will have to create GitHub PAT. More about it in Localstack_config.md file.

Debugging Core Services Locally

For core services, we rely on localstack for emulating AWS services. For debugging Lambda functions, you can access detailed logs directly from the docker container where the Lambda is running. This can be done using:

• Docker Desktop

Testing

To run all unit and integration tests for all packages:

pnpm -r test

Under the hood, the command runs pnpm test in each packages. Alternatively to run unit tests for a single package, you can cd into its directory and run pnpm test.

To run end to end tests, please visit the pets UI Cypress Section

By default, backend logs are hidden in tests as they could get noisy. To view your backend log messages and errors in tests, add the line below to configs/.env.test.local:

LOG_LEVEL=info

Don't forget to remove afterwards🫣

Preloaded Test Data (Might be broken due to Authentication)

• Passport Number: ABC1234JANE
• Country of Issue: Barbados

Kindly check pets-core-services/src/applicant-service/fixtures/applicants.ts for more information on this applicant.

Deployment

• Before proceeding, ensure you have access to the AWS environment. Kindly check this guide on raising the request.

• Navigate to the actions page.

• At the side panel, Find on the workflow with name Pets Deployment - {target-env} and click on it.

• At top right corner, find the Run Workflow Button.

• Start the deployment workflow by clicking on the button and providing your branch name. Please note that this would overwrite any existing deployment at the target environment.

• If a PR is already raised for your branch, after successful deployment, you should receive an email with the deployment url

Workflows to trigger DB migrations

There are some migrations that can be applied to Applicant or/and Application tables. More details about them in this file

Automated dependency updates

Renovate

• The renovate.yaml workflow will run once at Midnight on weekdays.

• PRs for dependencies requiring security updates will be opened by the workflow.

Culture

As Engineers, we commit to…

• Create a learning-focused working environment.
• No finger pointing, the code is everyone’s responsibility, and we are all accountable for changes.
• Ensure that all code is well-tested.
• Encourage contribution from everyone.
• Keep it simple and straighforward.