Manage breast screening

The new service is a system for managing breast screening clinics, including:

• Viewing and managing daily clinic lists
• Tracking participants through their screening journey
• Managing participant information and status

Running the app

Setup

To install the toolchain dependencies and setup the project, run

make config

This command assumes you have a few things already installed:

• Docker container runtime or a compatible tool, e.g. Podman
• asdf version manager
• GNU make 3.82 or later

Usage

make local

This will start the development instance of postgres (via docker) and serve the app at http://localhost:8000

Local development

Tests

To run all the tests:

make test

Running make config beforehand will ensure you have necessary dependencies installed, including the browser needed by playwright for system tests.

Dependency management

Python dependencies are managed via poetry.

• poetry install installs dependencies from the lockfile
• poetry add and poetry remove adds and removes dependencies
• poetry run [COMMAND] runs a command in the context of the project's virtual environment

npm is used to manage javascript dependencies and frontend assets.

You can run make dependencies to install anything that's missing after pulling new changes from GitHub.

Frontend assets

To compile assets, run npm run compile

To watch for changes, run npm run watch

This will compile scss files to css and bundle javascripts with rollup.js.

Postgres database

The makefile spins up a postgres DB using docker/podman.

• make db starts it if not running
• make rebuild-db rebuilds it from scratch, including seed data

Migrations

Database migrations are handled by Django's database migration functionality

• poetry run manage.py migrate loads database migrations
• poetry run manage.py makemigrations generates new database migrations

Note the database migration runs in the deployment pipeline after the application deployment. The deployed code must be compatible with the schema before AND after the schema changes. This also removes potential errors when using a rolling app deployment as multiple app versions may access the database at the same time. To enforce it, make sure to always separate code changes and database migrations into different pull requests.

Django admin

We'll probably remove it before deploying to production, but currently Django admin is enabled.

To use it, first create a superuser

poetry run ./manage.py createsuperuser

Then run the app and navigate to http://localhost:8000/admin

Design

The service will be deployed as a web application, backed by a postgres database with authentication provided by NHS CIS2. In addtion to these elements we will deploy a gateway application to each breast screening unit that uses the service that will be responsible for interop with local hospital systems. The gateway will be developed in a future phase of this project and is not currently under active development.

Structure

The manage_breast_screening directory contains all the Django project code.

config is a subpackage containing the configuration. The other subpackages - such as clinics - are Django apps. These each represent a bounded context within our overall domain of screening events. Django apps can be built with customisability and extendability in mind, and published as python packages, but we aren't doing that yet.

To generate a new app, run:

poetry run ./manage.py startapp <app_name> manage_breast_screening/`

Entity relationship

Mermaid ERD

Manual Deployment

The build pipeline builds and pushes a docker image to Github container registry. The app is deployed to an Azure container app using terraform.

For each environment, e.g. 'dev':

1. Connect to Azure virtual desktop. Ask the platform team for access with Administrator role.
2. If not present, install the following software: terraform (version 1.7.0), git, make.
   • Run a Command prompt as administrator
   • choco install terraform --version 1.7.0
   • choco install terraform git make
3. Open git bash
4. Clone the repository: git clone https://github.com/NHSDigital/dtos-manage-breast-screening.git
5. Enter the directory and select the branch, tag, commit...
6. Login: az login
7. Create the resource group: make dev resource-group-init. This is only required when creating the environment from scratch.
8. Deploy:

   make dev terraform-plan DOCKER_IMAGE_TAG=git-sha-af32637e7e6a07e36158dcb8d7ed90be49be1xyz

9. The web app URL will be displayed as output. Copy it into a browser on the AVD to access the app.

Continuous deployment

When a PR is merged, Github actions securely triggers the deployment pipeline on the Azure devops pool running on the internal network. It currently deploys the dev environment automatically.

Access Azure devops to see the pipeline.

Application secrets

The app requires secrets provided as environment variables. Terraform creates an Azure key vault and all its secrets are mapped directly to the app as environment variables. Devs can access the key vault to create and update the secrets manually.

Note the process requires multiple steps to set up an environment initially.

Contributing

• Make sure you have pre-commit running so that pre-commit hooks run automatically when you commit - this should have been set up automatically when you ran make config.
• Consider switching on format-on-save in your editor (e.g. Black for python)
• (Internal contributions only) contact the #screening-manage team on slack with any questions

Makefile and Scripts

scripts/ contains various scripts that can be used in the CI/CD workflows.

For more information, see the following developer guides:

• Bash and Make
• Scripting Docker

Licence

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

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