notarial-api

This ia a monorepo used for the notarial services apis, which power the prove your eligibility to a foreign government forms.

Prerequisites

1. A node version manager, like nvm, or n
2. node 24.x.x
3. npm 11 or later
4. Docker >= 3.9 - Install docker engine

Workspaces

• api
• worker

Getting started with Docker

You may use docker and docker compose to build and start the project with the right components (e.g. database, microservices), but will not be able to run the application(s) in dev mode.

To do this, simply run this command from the root of the project:

docker compose up -d

This will then run the server in a docker container in detached mode, allowing you to continue making commands through your terminal, but still keep the docker container running.

To rebuild the server after making some changes, run the following commands:

docker compose down
docker compose -d --build

Running the applications locally (without docker)

You may still need docker to start the databases.

From the root directory, docker compose up postgres

This will start the postgres container running on port 5432; with username user and password root, and a database created called notarial (postgres://user:root@localhost:5432/notarial). init.sql is also loaded as a volume into the container, and will create a database named queue (postgres://user:root@localhost:5432/queue). This is useful if you are going to be running forms-worker at the same time. If you are running postgres from this repo, you do not need to run it in forms-queue.

1. If you wish to send emails locally, you will need to authenticate your terminal with AWS. (formsawsauth prod)
2. Start the api npm run api -- start:local
3. start the worker NOTIFY_API_KEY=".." npm run worker -- start:local
4. Send a post request to http://localhost:9000/forms, use the payload found in notarial-api/api/src/middlewares/services/UserService/personalisation/__tests__/fixtures/marriageTestData.ts, or run the form runner locally, with the webhook configured to http://localhost:9000/forms.

Dependency security

• Commit .npmrc and package-lock.json.
• Use npm ci for ordinary installs and CI.
• ignore-scripts=true blocks dependency lifecycle scripts during install.
• Use npm install only when intentionally changing dependencies, then review the lockfile diff.

Code Quality

This project uses ESLint for linting and Prettier for formatting. The pipeline runs linting on build and stops on failure.

Available commands:

• npm run format — Run formatting and fix issues
• npm run lint — Run linting

Code Security

This project runs package vulnerability scanning. The pipeline runs this on build and stops on failure.

Available commands:

• npm run security — Run package vulnerability scan

---

CI/CD

There is a CI/CD pipeline currently set up for deploying new versions of the project to test environments. For more information, please refer to the CI/CD docs

This project uses semantic-release. This allows for automatic versioning of the project based on the commit messages when merging.

When merging, prefix the pull request subject with

• chore: for changes which should not increment the version number (like documentation changes)
• fix: for bug fixes, (increments the patch version)
• feat: for new features (increment the minor version)
• BREAKING: for major changes (increments the major version)

Releases are automatically generated from commit messages. Prefix each commit with one of the above prefixes to include the commit message in the generated message.

Testing

Currently, there is unit testing and integration testing set up for the api workspace. For more information, refer to the testing docs.