Setting up development for HyUi

Architecture

The root directory contains all the libraries that are used to power the HyUi dashboards.

  • api: This is a FastAPI app that does all the data wrangling and accessing of external sources such as to databases and web services. For each route there should be an equivalent mock route that allows this app to serve mock data when run in development. For example, if there is a /census/ endpoint then there should be a corresponding /mock/census endpoint that only serves mock data.
  • web: This contains the Plotly Dash web server code. It should only communicate with the api service. This allows the api service to provide mock data seamlessly when developing without needing to spin up other services to help development.
  • models: This contains all the Pydantic models that are used to share data between the api and web.
  • initialise: This sets-up the BaseRow instance that is used for configuration by the user.
  • baserow: We use baserow as a temporary database to that allows us to store information about patients without directly editing EMAP or EPIC. It is not relevant when running HyUI on your local machine, as all mock data will be stored locally. However, it is important to understand when deploying HyUI with live data within the NHS.

Architecture Ideals

  • web should only communicate with api for data. This allows us to entirely mock data for web when developing.
  • Communication between web and api should only be done in a defined way using models described in models. models is the only shared code between api and web.
  • Pages in web/src/web/pages should be independent of each other so there is minimal/no sharing between two sets of pages. Common code can be put in a separate module or package in web.

Local Development

Install Requirements

1. Clone the HyUi repository to your local machine.

git clone https://github.com/HYLODE/HyUi.git

2. Create Required Virtual Environments

pyenv virtualenv 3.11.0 hyui-web
pyenv virtualenv 3.11.0 hyui-api

As of Feb 2023, Python 3.11.0 causes diskcache / SQLalchemy issues with local development on some machines. For now, we recommend changing the above commands to instead use python 3.10.8.

3. Activate Virtual Environments

In one shell:

pyenv activate hyui-web

In another shell:

pyenv activate hyui-api

These will be the Python virtual environments that contain all the dependencies for the Dash web app and the API backend.

4. Install the Website app requirements

In the hyui-web terminal in the root directory:

pip install -e "models[test]"
pip install -e "web[test]"

5. Install the API requirements

In the hyui-api terminal in the root directory:

pip install -e "models[test]"
pip install -e "api[test]"

6. Install the pre-commit Hooks

In your shell (hyui-api or hyui-web) run the following command:

pre-commit install

6. Configure Environment Variables

You will need to create and configure a .env file in your directory root.

An example environment variable file can be found at .env.example. The environment variables for each app are documented in the Pydantic Settings classes in web/src/web/config.py and api/src/api/config.py. An important one for development and production is the WEB_API_URL variable. This should be set to the host and port of your api server so most likely something like http://api:8000 for running in Docker or http://localhost:[port]/mock for development. The port needs to line up with that specified when starting the FastAPI server below (we have used 8092 throughout these docs).

Note that in development a /mock path has been added. This allows the Dash web app to use all the mock endpoints instead of the live endpoints.

The environment variables are required, and the application will fail if any of these are missing when it attempts to run.

7. Running The Servers Manually When Developing

The web server when in the hyui-web shell:

env $(grep -v '^#' .env | xargs) python -m web.app

The API server when in the hyui-api shell:

env $(grep -v '^#' .env | xargs) uvicorn api.main:app --reload --port 8092

Ensure you replace .env with the correct path to your development .env file. The command env $(grep -v '^#' .env | xargs) loads the contents of the .env into the environment just for the current execution. The grep -v '^#' part excludes lines beginning with a # in the env file.

The --port specified in the hyui-api command should match the port in the WEB_API_URL variable of your .environment.

You can run both these commands from within vscode or pycharm - see instructions here.

Development within the NHS

Further information on developing within the NHS found on the Deployment page.