FebriLogic

Guiding clinicians through the fever puzzle
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Entity-Relationship Diagram (ERD)
   • Built With
   • Deployment
2. Getting Started
   • Prerequisites
   • Installation
   • Running the FastAPI Backend
   • Running the Streamlit Frontend
3. Roadmap
   • FastAPI Backend
   • Streamlit Frontend
4. Contributing
5. License
6. Contact
7. Acknowledgments

About The Project

FebriLogic is a clinical decision support tool that helps healthcare professionals quickly and accurately differentiate between acute febrile illnesses (AFIs). It leverages real-world data and a novel diagnostic algorithm to provide evidence-based insights at the point of care.

(back to top)

Entity-Relationship Diagram (ERD)

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Deployment

• 
• 

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

• Python 3.12+

  # Debian-based distros
  sudo apt-get install python3

• python3.12-venv for Debian-based distros

  # Debian-based distros
  sudo apt-get install python3.12-venv

Installation

1. Get free API keys at Resend

2. Clone the repo

   git clone https://github.com/muhammadazzazy/febrilogic.git

3. Navigate into the project directory

   cd febrilogic

Running the FastAPI Backend

4. Navigate into app/apis

   cd app/apis

5. Create a .env file

   # Required file path for the symptom and disease data.
   SYMPTOM_WEIGHTS_FILE=""
   
   # Required file path for disease biomarker statistics.
   BIOMARKER_STATS_FILE=""
   
   # Optional. Defaults to HS256.
   ALGORITHM="HS256"
   
   # Optional. Defaults to 30 minutes.
   ACCESS_TOKEN_EXPIRE_MINUTES=30
   
   # Required secret key.
   SECRET_KEY=""
   
   # Required Postgres database URL.
   POSTGRES_DATABASE_URL=""
   
   # Optional. Defaults to 0.0.0.0.
   FAST_API_HOST="0.0.0.0"
   
   # Optional. Defaults to 8000.
   FAST_API_PORT=8000
   
   # Optional. Defaults to http://localhost:8501
   STREAMLIT_BASE_URL="http://localhost:8501"
   
   # Required for sending verification emails.
   RESEND_API_KEY=""
   
   # Optional. Defaults to 3.
   RESEND_MAX_RETRIES=3
   
   # Required file path for the verification email template.
   VERIFICATION_EMAIL_TEMPLATE="html/verification_email.html"
   # Required.
   SUPPORT_REQUEST_TEMPLATE="html/support_email.html"
   
   # Required.
   PASSWORD_RESET_EMAIL_TEMPLATE="html/password_reset_email.html"

6. Create a virtual environment for backend

   # Linux
   python3.12 -m venv .venv
   
   # Windows
   python -m venv .venv

7. Activate the virtual environment

   # Linux
   source .venv/bin/activate
   
   # Windows
   .\.venv\Scripts\activate

8. Install backend dependencies

   pip install -r requirements.txt

9. Navigate out of the app/apis directory

   cd ..

10. Run the FastAPI app

    # Linux
    python3 -m apis.main
    
    # Windows
    python -m apis.main

Running the Streamlit Frontend

11. Navigate into ui

    cd ui

12. Create a secrets.toml file inside app/ui/.streamlit

    FAST_API_BASE_URL = "http://localhost:8000"
    FAST_API_CONNECT_TIMEOUT = 10
    FAST_API_READ_TIMEOUT = 30

13. Create the virtual environment for frontend

    # Linux
    python3 -m venv .venv
    
    # Windows
    python -m venv .venv

14. Activate the virtual environment

    # Linux
    source .venv/bin/activate
    
    # Windows
    .\.venv\Scripts\activate

15. Install frontend dependencies

    pip install -r requirements.txt

16. Run the Streamlit app

    streamlit run main.py

(back to top)

Roadmap

FastAPI Backend

• Implement patient data APIs:

  • POST /api/patient/{id} - add a patient to the patients table in the Postgres database

  • GET /api/patient - fetch patient information from the patients table in the Postgres database

  • POST /api/patient/{id}/diseases - add diseases the patient tested negative for to the patient_negative_diseases table in the Postgres database

  • POST /api/patient/{id}/symptoms - add patient symptoms to the patient_symptoms table in the Postgres database

  • POST /api/patient/{id}/biomarkers - add patient biomarkers to the patient_biomarkers table in the Postgres database

  • POST /api/patient/{id}/calculate - calculate the probabilities of diseases using the symptoms layer and symptoms+biomarkers layer

• Implement biomarker data APIs:

  • GET /api/biomarkers - fetch metadata of biomarkers from the biomarkers table including the name (if any), abbreviation, standard unit, and reference range of each biomarker
  • GET /api/biomarkers/units - fetch a mapping between the biomarker abbreviations and their corresponding units based on data in the biomarkers, units, and biomarker_units tables in the Postgres database

• Implement utility APIs:

  • GET /api/countries - fetch a listing of all countries (alphabetical) from countries table in the database
  • GET /api/diseases - fetch a listing of all possible diseases a patient can test negative for from diseases table in the Postgres database
  • GET /api/symptoms/categories-definitions - fetch a mapping between the symptom category, associated symptoms, and their definitions based on the data in the symptoms and symptom_categories tables in the database
  • POST /api/contact - send support requests with sender's name and email address, subject, and body to FebriLogic's support email address

• Implement authentication APIs:

  • POST /auth/ - register a new user by sending verification email
  • POST /auth/token - login to the app and obtain JWT token
  • POST /auth/request-password-reset - send password reset email
  • POST /auth/reset-password - reset the user's password
  • POST /auth/change-password - change the password of an already logged-in user

Streamlit Frontend

• Add Home page

  • Cookie consent dialog
  • Description of what FebriLogic is
  • Note indicating the project’s funding source, academic lead, and university affiliation
  • Supported United Nations (UN) Sustainable Development Goals (SDGs)
  • Disclaimer on tool usage

• Add Login/Register page

  • Form for user login/registration via email and password
  • Option to reset password after entering email

• Add Reset Password page

  • Form for resetting the password when user is locked out of their account via the password reset email and token
  • Form for changing password while user is logged in

• Add Patient Information page

  • Selectbox to add a new patient or select an existing patient
  • Form to submit patient info with selectboxes (sex, race, and country), optional text field for city, and number field for age
  • Reset button to clear all fields

• Add Disease-Specific Tests page

  • Selectbox to choose a patient
  • Form containing checkboxes for diseases and submit button to add diseases the patient tested negative for
  • Reset button to clear disease checkboxes

• Add Symptom Checker page

  • Selectbox to choose a patient
  • Form containing checkboxes for symptoms and submit button
  • Reset button to clear symptom checkboxes

• Add Biomarkers page

  • Selectbox to choose a patient
  • Checkbox for each biomarker indicating whether it was measured
  • Box for each biomarker to capture its value
  • Selectbox for each biomarker to choose the unit
  • Button to submit patient biomarkers
  • Reset button to clear biomarker checkboxes

• Add Results page

  • Selectbox to choose a patient
  • Button to calculate the disease probabilities for symptoms layer and symptoms+biomarkers layer
  • Ranked diseases with probabilities for symptoms layer and symptoms + biomarkers layer

• Add Contact Us page – send support emails

• Add Privacy Policy page – GDPR privacy policy

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Muhammad Azzazy - [email protected]

Project Link: https://github.com/muhammadazzazy/febrilogic

(back to top)

Acknowledgments

• Pylint (VS Code Extension)
• Pylance (VS Code Extension)
• autopep8 (VS Code Extension)
• Img Shields
• REST Countries

(back to top)