To my father, recently diagnosed with a squamous cell carcinoma, that inspired me on pursuing this project with his hope of finding a suitable immunotherapy clinical trial to participate in case the conventional treatment does not erradicate the tumor.

Speranza, the Italian word for Hope.

The main goal of this project is to give a pinch of hope to cancer patients and their friends and relatives by introducing them to the latest advancements within the immunotherapy world, contributing to an easier access to clinical trials information available worldwide.

On top of this, provide registered users to share their stories/testemonies/comments about any given clinical trial.

"Hope is the life we live, the attitude we carry, the gift we give others. Hope is the energy, the courage and the strength to keep believing in the goodness of life, God and the people around us."

Froyle Davies

1. UX

   1.1 User Goals and Stories

   1.2 User Requirements and Expectations

   1.3 Company Goals

   1.4 Design Choices

2. Wireframes and DB structure

3. Features

   3.1 Existing Features

   3.2 Future Features

4. Languages, Libraries, Frameworks and Tools

   4.1 Languages

   4.2 Libraries

   4.3 Frameworks and Databases

   4.4 Tools

5. Testing and Debugging

6. Deployment

7. Credits and Acknowledgments

   7.1 Credits

   7.2 Acknowledgments

[Back to top]

As a user I aim for:

• A simple and intuitive website.
• Easy navigation across pages.
• Visually attractive and accurate information.
• Appealing call-to-actions.

As a user, I want to:

• Get a brief introduction about what is immunotherapy.
• Access the most recent clinical trials available regarding immunotherapy.
• Shortlist the most interesting clinical trials into my dashboard and check all my contributions to the community.
• Share and edit my opinions and see other users comments/reviews concerning a specific clinical trial.

[Back to top]

• Easy navigation.
• Reliable information.
• Good responsiveness across multiple devices and browsers.
• Immediate feedback on data inputs and/or submissions.
• Call-to-actions functioning properly.

• Updated and clear information about the clinical trials.
• Links must be working properly to reach the target with any setbacks.
• External links must open in a new tab.
• Easy interaction with other users.
• Proper feedback handling an error.
• See and edit my comments in an easy way.
• Access a specific clinical trial comment section easily.

[Back to top]

• Provide healthcare patients, their family and friends, with the necessary information about clinical trials working with immunotherapy.
• Give doctors an easy way to look for potential clinical trials to recommend their patients.
• Advocate online for the immunotherapy approach as the future of medicine.
• Provide a safe space for users to share their stories and experiences in regard to a specific clinical trial.
• Engage the community in active discussions and in sharing their experiences/testimonies.

[Back to top]

Throughout out the website, I will be using icons provided by FontAwesome.

The icons used are self-explanatory and aid the navigation of the user, bringing an intuitive imagery to the website.

[Back to top]

The structure of this website will be quite simple as the main focus is on the data handling. Therefore, the website will consist of mainly 3 pages, the Landing Page, the Clinical Trials and the User's Dashboard page, as know as "My Trials & Reviews".

Throughout the entire website, the user will constantly have access to the Navigation bar, displaying according to the need the necessary sections.

Concerning the footer, it will display some contact information and any other less relevant content.

The Landing page will showcase the immunotherapy as the future of cancer fighting with a brief introduction and promoting the website as a safe space for the community to share their experiences. Also, an inspirational sentence will give the user the proper perception of the web page intent.

Below, the user will be able to see the most recent comments to the clinical trials. If the user wants to participate, they will have to properly register afterwards in order to access the entire set of clinical trials with the comments section feature available.

Also, on top of the landing page, two call-to-action buttons will be displayed to transmit the user the right perception of the need to create a user account to be able to access the full features of the website.

The user's authentication method used on this website is adapted from the corresponding lesson of the Code Institute Full Stack Software Development Course.

After a user is registered and logged in, it will not only have full access to the entire set of clinical trials but also access the comments section per trial.

Whilst the user is not registered/logged in, he can only access the general information but will not be able to participate in the discussions.

This page is powered by a search feature in order to easily find the most suitable clinical trial for its needs.

All the clinical trials will be displayed as cards that will include an icon to shortlist the clinical trial or a trash bin icon if the user wants to remove it from through this page and not through its own dashboard.

The user's dashboard will display the shortlisted clinical trials, as well as all the contributions that the user gave to the community.

The comments section will only be displayd when the user is logged in, and will be available through a modal where all the comments for any given clinical trial will be displayed, sorted by date (the newest first).

A simple edit page as been created during the development process in order to tackle the difficulties originated by having an edit section in a second modal. The page retrieves the user comment within a text area that the user chose to edit, giving him the option to edit the comment in a simple efficient way.

[Back to top]

[Back to top]

Small devices

Medium Devices

Large devices

[Back to top]

[Back to top]

• Sharing Comments: Users can share their experiences/testimonials/reviews/opinions with every registered user for any given clinical trials.

• Last 5 Comments Preview: Gives every user a sneak peek about the ongoing discussions within the community making them wanting to participate and be part of it.

• Flash Messages: Provides immediate feedback to the user on the CRUD functionalities across the webpage.

• Open Trials API: Provides the website with all the public information available regarding the clinical trials.

• User Authentication: Limiting/Providing some users access to website resources.

• Dynamic Navbar: Adaptive Navbar based on User's Authentication.

• Clinical Trials Shortlist: Provides the user with direct access to the trails bookmarked as favourites for an easier access to the discussions.

• Search Bar: Facilitates the user to find the most relevant clinical trial in order to engage with the community on that specific topic.

• Trials Counter: Gives the user a quick overview of the amount of trials that are potentially relevant.

• Error Handlers: Allow user to navigate back to the homepage in case of a 404 or 500 errors.

• Randomized Unsplash pictures from my Clinical Trials Public Collection: Gives the clinical trials cards a random picture from that collection, allowing the user to be less scared about the medical terms displayed that might scare the user of trying to interact with the website and community.

[Back to top]

• Comments counter on every clinical trial card for user to assess the activity level of a discussion, visible to all the users.

• Amount of users that shortlisted a specific trial, visible on each specific card to all the users.

• Pagination in Clinical Trials and My Trials & Reviews pages, as well as in the Add Trial Modal where comments are displayed.

• Automatic cookies deletion after a certain idle time to increase security.

• Request a confirmation about the correctness of the user's action prior deleting a comment or saving a comment edition, or remove clinical trial from the shortlist.

• Counter for number of trials and contributions in user's My Trials & Reviews dashboard.

[Back to top]

[Back to top]

• HTML
• CSS
• Javascript
• Python
• Jinja2

[Back to top]

• jQuery
• FontAwesome
• Google Fonts
• Unsplash

[Back to top]

• Bootstrap
• MongoDB
• Flask

[Back to top]

• Git
• Gitpod
• Balsamiq
• Coolors
• Contrast-Checker
• Free Logo Design
• TinyPNG
• Favicon
• RandomKeygen
• Swagger
• Techsini
• W3C-Markup-validation
• W3C-Jigsaw
• W3C-Spell Checker
• Google-Lightouse
• JSHint

[Back to top]

[Back to top]

Note 1: Bootstrap was used throughout the entire application guaranteeing an excellent responsiveness.

Note 2: In order to improve the UX, in case that one day a trial is deleted from the API, I wanted to make sure that the user would not face an error preventing him of accessing its dashboard. Therefore I rearraged the 'View Trial' view and added an else statement in case the result attained is 0.

Note 3: After running the Google-Lightouse Tool, I noticed that the Unsplash API, considering the amount of results retrieved in the 'Clinical Trials' is having a strong negative impact in the loading performance, especially in mobiles. Thereof, in the future, I intend to save locally all the images of this collection in order to enhance the loading time of this page.

Note 4: The usage of modals came with additional challenges, especially due to the fact of the dynamic IDs. Moreover, when the authenticated user performs an action inside the modal, namely commenting or adding/removing the trial to/from the favourites, the modal closes and redirects the user to the Clinical Trials Pages, not keeping the user inside the modal, which may cause some discomfort. The same goes for when the user performs these same actions, starting from the 'My Trials & Reviews' page. Nonetheless, here it is aggravated by the fact that the user is redirected to another page and not to the one he started at. Because modals are an excellent visual tool to any website, I would like to keep it. Therefore, in the future I want to deep dive into this issue in order to increase the UX without sacrificing this feature. If in the end this will not be possible, I can make sure all actions have dedicated pages so the re directions won't affect too much the UX.

[Back to top]

all_trials = []
    for comment in comments:
        result = client.trials.searchTrials(
            q=comment["trial_id"]).result()
        if result not in all_trials:
            all_trials.append(result)

[Back to top]

I have created Speranza using Github and Gitpod to write my code.

Then, I used commits to git followed by "git push" to my GitHub repository.

This project has been deployed to Heroku which was previously connected with the Speranza Repository in Github to automatically get all the pushes done in Github.

To run this project locally, follow the next steps:

This project can be run locally by following the following steps: ( as I have user used Gitpod for development, the next steps are specific to it. Adjustment may be necessary depending on your IDE. More information about installing packages using pip and virtual environments here.

To clone the project:

1. From the application's repository, click the "code" button and download the zip of the repository. You can also clone the repository using the following command in your terminal:

   git clone https://github.com/arturmpinho/Speranza.git
   

2. Access the folder in your terminal window and install the application's required modules using the following command:

   pip3 install -r requirements.txt
   

3. Sign-in or sign-up to MongoDB and create a new cluster

   • Within the Sandbox, click the collections button, folowed by a click in Create Database (Add My Own Data) called speranza
   • Set up the following collections: users, trials and comments Click here to see the exact Database Structure
   • Under the Security Menu on the left, select Database Access.
   • Add a new database user, and keep the credentials secure
   • Within the Network Access option, add IP Address 0.0.0.0

4. In your IDE, create your env.py file at the root level of the application, containing the following lines and variables:

   import os
   
   os.environ.setdefault("IP", "0.0.0.0")
   os.environ.setdefault("PORT", "5000")
   os.environ.setdefault("SECRET_KEY", "YOUR_SECRET_KEY")
   os.environ.setdefault("MONGO_URI", "YOUR_MONGODB_URI")
   os.environ.setdefault("MONGO_DBNAME", "DATABASE_NAME")
   
   

   Please note that you will need to update the "YOUR_SECRET_KEY" with your own secret key, as well as the YOUR_MONGODB_URI and DATABASE_NAME values with those provided by MongoDB.

   Tip for your YOUR_SECRET_KEY: you can use a Password Generator in order to have a secure secret key.

   It is recommended to use minimum the 'Fort Knox Passwords'.

   To find your YOUR_MONGODB_URI, go to your clusters and click on 'connect'. Choose 'connect' your application and copy the link provided. Don't forget to update the necessary fields such as password and database name.

   If you plan on pushing this application to a public repository, ensure that env.py is added to your .gitignore file in order to safeguard your sensitive information.

5. Run your application locally typing the following command in your terminal.

   python3 app.py. 
   

1. Login to your Heroku account and create a new app. Preferably, choose the region where you are located.

2. Ensure the Procfile and requirements.txt files are created and updated in your local repository.

   Requirements:

   pip3 freeze --local > requirements.txt
   

   Procfile:

   echo web: python app.py > Procfile
   

3. The Procfile should contain the following line:

   web: python app.py
   

4. Go to your "deployment method"-section and Choose "Github" for automatic deployment.

5. Below, make sure your Github user is selected, and then enter the name of your repository. Click "search". When it finds the repository, then click the "connect" button.

6. Go up and click "settings" and then scroll down and click "Reveal config vars".

Set up the same variables as in your env.py (IP, PORT, SECRET_KEY, MONGO_URI and MONGODB_NAME):

IP = 0.0.0.0
MONGO_DBNAME = DATABASE_NAME
MONGO_URI = YOUR_MONGODB_URI
PORT = 5000
SECRET_KEY = YOUR_SECRET_KEY

1. Click in "Deploy" tab. Scroll down and click "Enable automatic deployment".

2. Just beneath, click "Deploy branch". Heroku will now start building the app.

3. In order to commit your changes to the branch, use git push to push your changes via your IDE.

[Back to top]

[Back to top]

• All software and applications used to create this website are mentioned above in section [Languages Libraries Frameworks and Tools](#languages-libraries-frameworks and-tools).
• MDN WebDocs

• You can find all the images sources through the Unslplash collection prepared here.

• OpenTrials and their article made available here.

[Back to top]

To Stackoverflow community and to W3Schools for all the content made publicly available.

To Julian Nash for the great tutorial Working with Jinja templates - Python on the web - Learning Flask Series Pt. 6.

To Paul Walsh on the handy notebook on how to handle the OpenTrials API.

To my mentor, Anna_Villanueva, for all the inputs and guidance throughout this project.

To my friends and family that took time to test the website and for their valuable recommendations and insights.

A special thanks to Anouk, for all the support given suring these difficult past months and for all the suggestions and guidance during the implementation of this project.

[Back to top]