Manage breast screening Django spike

This repo is a spike to explore using Django as the framework for our new service.

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 run

This will serve the app at http://localhost:8000

Local development

Tests

To run all the tests:

make test

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.

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

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/`

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.