Hello developers! I hope your term is going well. This document will serve as an entry point into the project, and provide a brief overview of what we have implemented so far.
As you are probably aware, BC CAHS is looking to digitize their sample registration process. Currently, BC CAHS accepts all sample submissions through a physical form. This form is then manually transposed into an excel sheet, which houses all information about the submitted sample and lab results. BC CAHS aims to replace this excel based system with a database that can be filtered, effectively searched through and edited.
Throughout our project term, our team’s focus was on designing a centralized database that could be used by BC CAHS lab workers. Our emphasis was on implementing this database, basic user authentication and a front-end component which allows CAHS staff to filter, search and edit existing database elements. You will continue to build upon these existing features!
Key Development Points:
- Our database is built on PostgreSQL. We suggest checking out the database folder and looking through the migration file to see our current DB structure. PGadmin is what we used for testing and development.
- Docker is being used to ensure consistency across all development environments. Make sure to install Docker Desktop.
- Hope you like Express as a backend framework!
- React is used in the frontend. We tried to keep things as contemporary as possible. Material UI is used throughout for styling.
If you have never used Docker before, it may feel somewhat intimidating. But once you get used to using it, Docker becomes a very useful and valuable developmental tool. This section will run through how to get your project up and running by using docker.
Make sure you have all the nessecary tools downloaded.
- npm
npm install npm@latest -g
- express
npm install express
- Downlod Docker!
Once you have both the code base and nessecary programs downloaded on your machine, it is time to start devloping!
-
Open a terminal, within your code base, and run
docker-compose build
This command builds all services, including any database migrations. It's an essential step!
-
Now your sevices are built, run docker-compose up.
docker-compose up
This command creates, starts and attaches containers for a service. It handles configuration steps outlined in the dockerfile, like npm start, automatically.
-
The project is now running! Open http://localhost:3000/login. As of right now, anyone can sign up to create an account. Your server will be running on http://localhost:8000 .
-
Hot reloads are supported. Changes to your code, once saved, will prompt a reload and rendered.
-
Once you are ready to stop development, be sure to run the following command:
docker-compose down
This command stops and removes containers, networks, volumes and other images created by the docker-compose up command.
- If you run into issues with a corrupted database and need to locally delete your
dbfolder, just follow these steps again!
-
Note (for Linux & Mac users only) you can simply be at the root directory and run this command :
npm run devCheckout package.json in the root directory to see what is actually happening!
- If you run into issues where docker tells you that you are out of space, you can clean up all the dangling images, containers, and volumes in VOLUMES.
- If you want to update any local development environment settings such as changing the running PORTs or updating the data path of postgres, please find them in
docker-compose.yml. Don't forget todocker-compose down,docker-compose build, anddocker-compose upagain to run the application with new settings applied.
The functionality of the site is pretty straight forward. We'd encourage you to play around with the site before you begin further development. Best place to start would be signing up and logging in (authorization code can be found ). You'll be greeted by the following page:
No data has been inputted yet. The Frontend code can be found here --> client\src\app\pages\Home\Sample. Let's start logging in some data. Our submission form, and all provided fields, are based upon the specifications of the BC CAHS.
If you want to take a look at the code, we suggest checking out --> client\src\app\pages\Home\components\SampleInput.js. Be sure to also look into the server side of things to see the connection between frontend and backend --> server\router\submission.js!
After you have logged in data, it'll be rendered in both the sample landing page and in the status page. Check out the code for the Status page here --> client\src\app\pages\Home\Status.
Mess around with inputting the data, and applying different fields on the pages mentioned above. We've tried our best to document the code through-out the development, so hopefully you will be able to dive in quickly and build upon the work that we have started.
From our understanding, alot of the work you will tackle will centered on data visualization for the Data/Report Templates. We'd recommend looking closely at the implementation of our Status page code, and understanding the way in which data is being grabbed from postgres.
Currently, the application is deployed in AWS for demonstration and presentation purposes. Sitting in front of the application is the NGINX webserver that will redirect all /api routes to the API server at PORT 8000 and the others will be redirected to the default folder of NGINX /usr/share/nginx/html (details can be found in the file nginx.conf under folder deployment of this github).
Because we separated the React application from the stack, there is a file called docker-compose.ec2.yaml to be specifically used for deployment to AWS.
The ideal deployment should not contain the Database within Docker because if docker is down, all the data might be lost. Therefore, it is better to have either a self-hosted database such as AWS RDS, or AWS-managed relational database Aurora, or have CAHS host a Database separately so we can have a proper backup plan to prevent data being lost.
* Note: The above proposed deployment might not well suited with the infrastructure of Arbutus cloud, but there will have simililar components/entities/services that can replace the proposed AWS services. For example, we can replace AWS EC2 instance by any service Arbutus Cloud offers that can provide a running server.
-
Authentication
- Basic User Authentication
- Login
- Logout
- Session persistence
- Advanced User Authentication
- Admin/Limited privileges
- Email, Phone call, or SMS verification upon registration
- Retrieve forgotten password
- Basic User Authentication
-
Structure and Create Database
- Create Database schema/ERD
- Maintain well-defined and clear table format to support further expansion
- Create basic migration upon running the server
- Better design for database migration (currently, the database migration script runs whenever the application is spinning up. This is not a good practice. Consider using
knexfor better migration plan)
-
Form/Submission
- Create a new form
- Update an existing form
- Edit status of the form
- Display the status chart group by requeted analysises
- Render and update the data
- Be able to update the form on Status page
- Additional data representation fields (Invoices, etc...)
- Report template section
-
Admin panel (suggestions)
- Allow admin to remove/block a user
- Allow admin to add/remove privileges from a user
-
Deployment
- Deploy to AWS for presentation
- Deploy to BC CAHS Arbutus Cloud
-
To be determined by BC CAHS
I hope this section is not redundant! We used the following git work-flow in our developmental process:
- Fork the Project
- Create your Feature Branch (
git checkout -b name/feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin name/feature/AmazingFeature) - Open a Pull Request and request for reviews
Some useful guides or reference sheets that you may find helpful early on in development.
- https://gist.github.com/jonlabelle/bd667a97666ecda7bbc4f1cc9446d43a
- https://dockerlabs.collabnix.com/docker/cheatsheet/
- https://devhints.io/docker-compose
Distributed under the MIT License. See LICENSE.txt for more information.