HeartBeat 💓

A heart failure detection system

Cardiovascular diseases (CVDs) are the number 1 cause of death globally, taking an estimated 17.9 million lives each year, which accounts for 31% of all deaths worldwide. Four out of 5CVD deaths are due to heart attacks and strokes, and one-third of these deaths occur prematurely in people under 70 years of age. Heart failure is a common event caused by CVDs and this dataset contains 11 features that can be used to predict a possible heart disease.

People with cardiovascular disease or who are at high cardiovascular risk (due to the presence of one or more risk factors such as hypertension, diabetes, hyperlipidaemia or already established disease) need early detection and management wherein a machine learning model can be of great help.

Source: https://www.kaggle.com/datasets/fedesoriano/heart-failure-prediction

In this project, we create a complete solution featuring a FastAPI backend and a React frontend. We perform Exploratory Data Analysis (EDA) and develop a machine learning model using scikit-learn.

🚀 Running the project

Important

The following instructions assume you have Docker and Docker Compose installed.

1. Clone the repository and navigate to the project directory.

   git clone https://github.com/billsioros/heartbeat
   cd heartbeat

2. Edit the .env file.

   POSTGRES_DB='heartbeat'
   POSTGRES_USER='guest'
   POSTGRES_PASSWORD=')M8z*yss$cRxw7(&'
   
   BACKEND_DATABASE__URI = 'postgresql://guest:)M8z*yss$cRxw7(&@database:5432/heartbeat'
   BACKEND_CHECKPOINT_PATH = './model.joblib' # The model checkpoint should be in your project directory. This is necessary for mounting the volume in Docker. Leave it as is.

3. Build and start the services using Docker Compose.

   docker-compose up --build

The frontend and the backend should be now available at http://localhost:80 and http://localhost:8000, respectively. Make sure you also run poe manage database create to create the actual database (assuming you have correctly exported BACKEND_DATABASE__URI).

Troubleshooting

• To view the logs of a specific service, run:

  docker-compose logs <service_name>

• To stop the services, run:

  docker-compose down

• To remove the volumes along with stopping the services, run:

  docker compose down -v

Running the services outside of Docker

We use the Poetry Python package manager. Having installed Poetry you may now create a brand new virtual environment and install the project's dependencies.

export BACKEND_DATABASE__URI='postgresql://guest:)M8z*yss$cRxw7(&@localhost:5432/heartbeat'
export BACKEND_CHECKPOINT_PATH='./model.joblib'
poetry env use 3.11
poetry install
python src/api/app.py

Important

Set up PostgreSQL before starting the project with docker compose up database --d. Afterward, run poe manage database create to create the actual database. To tear down PostgreSQL, use docker compose down database -v.

Running the frontend:

cd src/web
nvm use 20
npm install
npm run dev -- --host --port 80

Note

Ensure you have Node.js 20 installed. We use nvm for this because it makes it easy to install and switch between Node.js versions. To install Node.js 20, run nvm install 20.

💻 Deploying to production

Deploying to production involves several crucial steps, including setting up a server, configuring DNS, and managing SSL certificates. Traefik simplifies many of these tasks, acting as a powerful reverse proxy and load balancer. For a comprehensive guide on deploying your FastAPI application with Traefik, read the full article here.

📑 Contributing

In order to locally set up the project first clone the repository:

git clone https://github.com/billsioros/heartbeat

Optionally, you can install pyenv to easily install Python 3.11:

pyenv install 3.11.4
pyenv local 3.11.4

Installing pre-commit hooks

Git hooks are scripts that run automatically to perform tasks like linting and formatting code at different stages of the development process. pre-commit is a tool designed to manage and share these hooks across projects easily. Having created a virtual environment and installed the required dependencies, you may run pre-commit install --install-hooks to install the git hook scripts.

Performing development operations via poethepoet

We are using poethepoet, to perform various development oriented tasks. Formatting, type-checking, as well as a few other operations, can be performed by running poe <task>. Please run poe --help (or poetry run poe --help), to list all available operations.

Writing your commit message

The project's version number and Changelog, depend on a consistent commit history. As a result, your commit message's format is extremely important. Before opening a pull request, please make sure that your commits strictly follow the Conventional Commits format.

🏷️ Credits

This project was generated with billsioros/cookiecutter-pypackage cookiecutter template.