ahwr-application-backend

Created from the Core delivery platform Node.js Backend Template.

• Requirements
  • Node.js
• Local development
  • Setup
  • Development
  • Testing
  • Production
  • Npm scripts
  • Update dependencies
  • Formatting
    • Windows prettier issue
• API endpoints
• Development helpers
  • MongoDB Locks
  • Proxy
• Docker
  • Development image
  • Production image
  • Docker Compose
• Dependabot
• SonarCloud
• Data Changes
• Licence
  • About the licence

Service Purpose

This service is the main backend for AHWR and handles the CRUD updates for applications, claims, herds and flags. API endpoints are provided for the public and internal frontends to interact with the data.

Service features

• Provides API endpoints for the public and internal frontends to interact with the data
• Processes incoming messages from an SQS queue to update the status of claims as needed
• Emits outbound events to various SNS topics to notify other services of changes to applications, claims, herds and flags
• Runs scheduled tasks to check for any claims that have been in a ON_HOLD status for over 24 hours and updates their status to READY_TO_PAY

Requirements

pre-commit

Please install pre-commit, as it is used to scan commits for secrets using Gitleaks.

Node.js

Please install Node.js >= v22 and npm >= v11. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

cd ahwr-application-backend
nvm use

Local development

Setup

Install application dependencies:

npm install

Development

Copy .env.example to .env and speak to the team for the relevant values.

To run the application in development mode run:

npm run dev

OR to run dockerised to mimic production environment run:

./scripts/start

Testing

To test the application run:

npm run test

Npm scripts

All available Npm scripts can be seen in package.json. To view them in your command line run:

npm run

Update dependencies

To update dependencies use npm-check-updates:

The following script is a good start. Check out all the options on the npm-check-updates

ncu --interactive --format group

Formatting

Windows prettier issue

If you are having issues with formatting of line breaks on Windows update your global git config by running:

git config --global core.autocrlf false

API endpoints

Endpoint	Description
GET: /health	Health
GET: /api/support/applications/{reference}	Request DB view of a given application, for support area in backoffice
GET: /api/support/claims/{reference}	Request DB view of a given claim, for support area in backoffice
GET: /api/support/herds/{id}	Request DB view of a given herd, for support area in backoffice
GET: /api/support/queue-messages	Request messages from SQS queue
GET: /api/applications/{oldWorldAppRef}/history	Request history for a specific old world application
GET: /api/claims/{claimRef}/history	Request history for a specific claim
PUT: /api/applications/{ref}	Update status of old world application.
GET: /api/applications/contact-history/{ref}	Request contact history for a specific application
PUT: /api/applications/contact-history	Potentially update contact history for a specific application
GET: /api/applications/latest-contact-details/{ref}	Request latest contact details for an application
POST: /api/applications	Create a new application
GET: /api/applications	Get all applications for a specific SBI
GET: /api/applications/{applicationReference}/claims	Get all claims for a specific application
GET: /api/applications/{applicationReference}/herds	Get all herds for a specific application
GET: /api/applications/{applicationReference}	Get a specific application
POST: /api/applications/search	Search for applications using specific criteria
PUT: /api/applications/{reference}/data	Update data for a specific application
PUT: /api/applications/{ref}/eligible-pii-redaction	Update eligibility for PII redaction for a specific application
GET: /api/claims/{reference}	Get a specific claim by reference
POST: /api/claims/search	Search for claims using specific criteria
POST: /api/claims/is-urn-unique	Check if the Unique reference has been used for any previous claims for a given SBI
POST: /api/claims	Create a new claim
PUT: /api/claims/update-by-reference	Update the status of a claim
PUT: /api/claims/{reference}/data	Update data for a specific claim
POST: /api/claims/withdraw	Withdraw a claim, recording the reasons in the withdrawalrequests collection
PATCH: /api/flags/{flagId}/delete	Mark a flag as deleted
GET: /api/flags	Get all the lags that exist
POST: /api/applications/{ref}/flag	Create a new flag against the given application reference
DELETE: /api/cleanup	Cleanup (delete) data for a given SBI, as used by performance tests etc

Development helpers

MongoDB Locks

If you require a write lock for Mongo you can acquire it via server.locker or request.locker:

async function doStuff(server) {
  const lock = await server.locker.lock('unique-resource-name')

  if (!lock) {
    // Lock unavailable
    return
  }

  try {
    // do stuff
  } finally {
    await lock.free()
  }
}

Keep it small and atomic.

You may use using for the lock resource management. Note test coverage reports do not like that syntax.

async function doStuff(server) {
  await using lock = await server.locker.lock('unique-resource-name')

  if (!lock) {
    // Lock unavailable
    return
  }

  // do stuff

  // lock automatically released
}

Helper methods are also available in /src/helpers/mongo-lock.js.

Proxy

We are using forward-proxy which is set up by default for Wreck.

Docker

Development image

Build:

docker build --target development --no-cache --tag ahwr-application-backend:development .

Run:

docker run -e PORT=3001 -p 3001:3001 ahwr-application-backend:development

Production image

Build:

docker build --no-cache --tag ahwr-application-backend .

Run:

docker run -e PORT=3001 -p 3001:3001 ahwr-application-backend

Docker Compose

A local environment with:

• Localstack for AWS services (S3, SQS)
• MongoDB
• This service.

docker compose up --build -d

Dependabot

Currently setup to work into four groups, so we don't have PRs per package. The updates run once a week, on a Monday. Except for the security group, which is advisory-triggered and ignores the schedule.

SonarCloud

Sonarcoud is enabled for this repository. All pull requests will be analysed. You can view the reports at Sonarcloud

Data Changes

Until the backoffice is setup for data changes it is necessary to run them on deployment. The changes only run if the environment variable is correct, and they have not been run before.

The data changes will only work in local, dev and prod, and not other environments.

No modification of the code is needed.

An environment variable needs to be setup on the CDP portal (or local) with the name DATA_CHANGE_DATA. The variable will contain an JSON object with two keys, version and data. The value of version will be the number of the ticket. The data value will be an array of objects as per the definition found in src/distributed-jobs/data-changes/schema.js

There cannot be spaces at all due to limitations of the CDP portal.

The version is used to create a lock/register, so the same version is never deployed twice (needed, between other things, because of multiple instances).

If for any reason there was a problem with the data you will want to add to version -{n} where {n} is just an incremented number.

By default a change applies to a claim (or, for herdReasons/herdCph/herdName, the herd it's currently associated with) and requires a claimRef. To update the application itself instead, set "target":"application" and omit claimRef - field is then the actual property name on the application document, e.g. createdAt (see APPLICATION_FIELD_TYPES in src/distributed-jobs/data-changes/schema.js for the fields this supports).

Examples

Deleting records: {"version":"1907","data":[{"claimRef":"FUDC-7F88-40CB","sbi":"106438775","applicationRef":"IAHW-1169-3902","action":"deletion","requester":"Some_Name","dateRequested":"2026-05-13T00:00:00.000Z"}, {"claimRef":"FUDC-7F88-40AD","sbi":"106438888","applicationRef":"IAHW-1169-4000","action":"deletion","requester":"Some_Name","dateRequested":"2026-05-13T00:00:00.000Z"}]}

Changing values: {"version":"1908","data":[{"claimRef":"FUDC-7F88-40CB","sbi":"106438775","applicationRef":"IAHW-1169-3902","field":"laboratoryURN","oldValue":"ab12345","newValue":"cd6789","action":"fieldChange","requester":"Some_Name","dateRequested":"2026-05-13T00:00:00.000Z"},{"claimRef":"FUSH-1E7B-8C83","sbi":"106908592","applicationRef":"IAHW-1467-F90C","field":"laboratoryURN","oldValue":"7300929","newValue":"ABC12345","action":"fieldChange","requester":"Some_Name","dateRequested":"2026-05-13T00:00:00.000Z"}]}

Changing the application's values (agreement date, i.e. createdAt - no claimRef needed): {"version":"1909","data":[{"applicationRef":"IAHW-JIMI-GJUC","sbi":"124578589","target":"application","field":"createdAt","oldValue":"2025-12-12T14:07:07.899Z","newValue":"2025-11-28T09:30:00.000Z","action":"fieldChange","requester":"Some_Name","dateRequested":"2026-09-11T00:00:00.000Z"}]}

Although the examples are separated, they can be mix and matched.

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.