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

You will need to manually install a few prerequisites to bootstrap everything:

• Docker container runtime or a compatible tool, e.g. Podman
• asdf version manager
• GNU make 3.82 or later
• The suggested build environment for pyenv

Then to install the rest of the toolchain, run:

make config

If you run into command not found: pip errors, make sure you have correctly configured your shell for asdf, i.e. updated the relevant dotfile, and reloaded it or opened a new shell.

Running the app for the first time

make local

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

Commands for local development

Dev server

make run

This will run the dev server without reloading seed data. This is a shortcut for poetry run ./manage.py server.

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 uv.

• uv sync installs dependencies from the lockfile
• uv add and uv remove adds and removes dependencies
• uv 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

• uv run manage.py migrate loads database migrations
• uv 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.

We are using django-linear-migrations to manage conflicts in the migration history. If you get a conflict in max_migrations.txt, you will need to:

1. migrate back to the common anscestor migration, e.g. uv run ./manage.py migrate mammograms 0030.
2. rebase your git branch
3. resolve the migration conflict using uv run ./manage.py rebase_migration.

If you have multiple migrations on your branch, you will need to squash them together before running rebase_migration.

Demo data

There is a make task to seed a non-production instance of the service with example data

• make seed-demo-data or make seed-demo-data ARGS=--noinput to skip the confirmation

This command wipes the database entirely before populating it with fictitious data. The data is contained in yaml files in the data directory and can be amended etc there as required.

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.

Display diagrams interactively:

• Run make diagrams
• Open http://localhost:8080/ in a browser
• Select views from the sidebar or double click on diagram elements

Alternatively, view all static diagrams.

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:

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

Deployment

See Deployment.

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

More documentation

Explore the docs directory.

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.