The AugMed App (Backend API)

AugMed is a web application, built for the UNC-Chapel Hill DHEP Lab, that allows the lab to collect data from participants in a user-friendly way. The app is designed to be used on any devices, and it allows participants to answer questions about their judgements for cases with potential Colorectal Cancer (CRC). The app is built using React, and the backend API is built using Flask and Python.

Live Website: https://augmed1.dhep.org/.

Note

Frontend Repository: DHEP Lab AugMed Frontend.

Local Environment Setup

Clone the repository if you haven't done so already, then follow these steps to set up your local environment:

1. Install Python

   Use the following command to install Python:

   brew install python@3.11

   After installation, verify the new version by running:

   python3 --version

2. Install Pipenv

   Pipenv is used to manage dependencies as it can automatically generate the Pipfile.lock, unlike virtualenv which requires manual generation of requirements.txt.

   pip install pipenv

   For installing further dependencies, use pipenv install <package> instead of pip install <package> to manage the dependencies efficiently.

3. Docker

   Ensure Docker is installed and running locally on your machine.

4. Python Path

   In the root path of the project, set the PYTHONPATH by running:

   export PYTHONPATH=$(pwd)

Running the Application

To run the application locally, follow these steps:

Important

Ensure you have activated your pipenv shell by running pipenv shell.

1. Ensure all dependencies are installed using Pipenv.

   pipenv install

2. Start your Docker containers if the application requires any external services like databases.
3. Use the following command to run the application under the src directory:

   flask run

   Adjust the command based on your application's entry point if different.
4. Alternatively, run the following command to start the application, at the root path of the project if there is any port conflict on your machine:

   flask run --host=127.0.0.1 --port=5001

Important

If your frontend is also running, ensure it is configured to communicate with this backend API. You may need to set the API URL in your frontend configuration. Also, you might need to use CORS (Cross-Origin Resource Sharing) if your frontend and backend are served from different origins. You can use the flask-cors package to handle this:

pipenv install flask-cors

Then, in src/__init__.py, add:

from flask_cors import CORS
# Then, after declaring `app` in the same file:
CORS(app, origins=["http://localhost:3000"], supports_credentials=True, expose_headers=["Authorization"],)

This will allow your frontend to make requests to the backend without running into CORS issues.

Testing

Pytest Naming

Pytest discovers tests following these naming conventions:

test_*.py
*_test.py

For more details, visit pytest documentation.

Running Tests

Execute your tests by running:

pytest

Ensure you are in the project's root directory or specify the tests' path.

Linting

To maintain code quality and consistency, run linting tools such as flake8 or pylint. Install your chosen linter via pipenv, then run it across your project. For example, with flake8:

pipenv install flake8
flake8 src

Black Formatting

It is highly encouraged to use Black for code formatting before every commit. You can run it as follows:

pipenv run black .

Run this inside a pipenv shell, from the root directory of the project. This will format all Python files in the project.

Database Setup and Migrations

Local Database

To set up the local database, firstly export the var in .env to local. Then run:

docker-compose up -d

And add a .env file in the root follow the .env_example

Database Migration

Database migration scripts are managed with Flask-Alembic under the src/migrations folder.

To modify the schema, use the following commands under the src:

flask db init  # Only needed the first time to create the migration repository.

flask db migrate -m "Create user table"

flask db upgrade  # Execute this if you pull new changes that alter the schema remotely.

Important

When you run flask db migrate, it generates a new migration script in the src/migrations/versions directory. Review this script to ensure it accurately reflects the changes you made to the models. If necessary, modify the script before running flask db upgrade. This is very crucial because the migration script might contain errors or false commands, like drop_table, which can lead to data loss. Always double-check the generated migration script before applying it.

Git Hooks

Configure your local hooks as follows:

git config core.hooksPath .githooks

This will ensure that your local git hooks are used instead of the default ones. You can find the hooks in the .githooks directory.

Deployment

The application is deployed using Docker and AWS services. The deployment process involves building Docker images, pushing them to AWS ECR, and deploying them to AWS ECS.

Specifically, the application is deployed to an AWS ECS cluster using Fargate. The deployment process is automated using GitHub Actions, which builds the Docker image, pushes it to ECR, and updates the ECS service.

It also uses Terraform to manage the infrastructure as code.

Tip

Visit the augmed-infra repository for more details on the infrastructure setup and deployment process.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.