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.

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 [email protected]

   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:

Note: 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

NOTE: 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

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.

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.

License

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