- 1. Introduction
- 2. Setting Up
- 3. User Stories
- 4. Components
- 5. Architecture
- 6. Dev Ops
- 7. System Testing
- 8. Appendix
Proposed Level of Achievement:
Artemis
Deployed Web Application
Link to our Web application: https://sendit-orbital2020.herokuapp.com/
Recommended to use with Google Chrome. Feel free to use the application on desktop or on a mobile phone.
(Note: We are using a free plan for Heroku, it might take awhile for the Application to load at first. The application may be slow initially, please be patient.)
Motivation
Have you ever needed to deliver a parcel somewhere but you are too busy to hand deliver it? Have you ever noticed that your trip from point to point can be more meaningful? Ever wanted to make use of the empty space in your vehicle?
Normal delivery services usually require at least a few days to deliver your parcel. With the advent of technology, we see companies like Grab and Uber making use of people's vehicles to provide carpool services to ferry people to locations near their destination. So why not we implement a parcel delivery service where people can help deliver parcels to locations that are near to their end destination?
Aim
We hope to make parcel delivery more efficient by providing a platform for commuters to help with deliveries.
Prerequisites:
- An IDE, eg. Visual Studio Code
- Python 3.7
- pip (Python package installer) available for download : https://pip.pypa.io/en/stable/installing/
- Node.js(for npm package manager) download at: https://nodejs.org/en/
- Conda, for managing virtual environments, download at : https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html#
- MongoDB, download at : https://docs.mongodb.com/manual/administration/install-community/
Setting up Project:
- Clone repository from https://github.com/mechastriker3/SendIt.git
- Directory Structure (blue = folder, white = files):
- Open the project in IDE(VSCode)
- Open Terminal(for MacOS)
- Start mongoDB
- Run
brew services start mongodb-community@4.2
- Run
- To start the frontend server:
- cd into /frontend directory
- Run
npm install(This will install the dependencies required for project to run) - Run
npm start - Once you see that it has compiled successfully means the server is active
Next, open a New terminal with the + button on the top right hand corner
- To start the backend server:
- cd into /backend directory
- Set up virtual environment (so that pip packages will be contained in the environment)
- Run
conda create -n myenv python **=** x.x anaconda(replace x.x with python version, in our case python 3.7) - This will create a virtual environment named myenv. Run
conda env listto check if the environment is created. You should see an environment myenv. - Next we will activate the virtual environment by running
conda activate myenv
- Run
You should see a (myenv) at the front:
- After our virtual environment has been set up, we need to install our requirements for the backend.
- Run
pip install -r requirements.txt
- Run
- To start the backend server:
- Run
python wsgi.py - You should see something like this:
- Run
Now that the frontend and backend servers are running you may test the application out with your own google accounts.
Note: App runs on local database as this app is in development mode.
High priority > Must Have: * * *
Medium priority > Should Have: * *
Low priority > Good to Have: *
A User is a general term for any one who uses our application, this includes a user that needs parcel delivered as well as deliverers.
| Priority | As a... | I want to be able to ... | So that I can ... |
|---|---|---|---|
| * * * | Sender | Add a delivery job | Have my parcel delivered by a deliverer |
| * * * | User | Login securely | Keep my account safe |
| * * * | User | View my job history | Keep a track record of all my previous transactions and jobs |
| * * * | User | View my ongoing jobs | Keep a track record of the status of my ongoing jobs |
| * * * | User | View my personal information | Ensure my information is correct |
| * * * | Deliverer | View a list of all the jobs available | Accept jobs from the list |
| * * * | Deliverer | Search and filter through the list of jobs | Find the jobs that is convenient and suitable for me |
| * * | Sender | Cancel a job i posted if it has not been accepted | Remove a job if i no longer need it |
| * * | Sender | View details of deliverer who accepted the job I posted | Keep in contact the deliverer |
| * * | Sender | Have a confirmation that my delivery was complete | Know when the delivery was completed |
| * * | User | Exchange reviews after a job | Provide my feedback based on the service provided |
| * | Administrator | Warn or ban users who are irresponsible on the platform | Prevent abuse of the application |
| * | User | Communicate with the other party | Keep in contact with the other party should there be any issues |
| * | Sender | Edit a delivery job's details if it has not been accepted | Change the details should there be any mistakes |
_Note: all the low priority features (features that we deem non vital for normal use of the application), will be mentioned in the section 4.2.4 Possible Future Implementations
Our web-application's frontend is made up of these main components:
- Landing Page
- About Page
- Dashboard
- Job Listings Page
- Jobs Accepted Page
- Jobs Posted Page
- Schedule Job Page
- User Information Page
- View Feedback Page
Below are some screenshots of the application:
Dashboard:
Job Listing Page:
(Note: All pages with tables have expandable rows. Click on the job for the row to expand)
Schedule Job Page:
User Information:
A Web-application that supports three main features. The user will be able to view their information on the profile tab, including their jobs accepted, jobs posted. Secondly, the user will be able to view all the job listings and accept jobs that they want to take up. Lastly the user will be able to post jobs up for delivery.
a. Login to account
- New User Sign Up
- Log out
b. User Profile
-
User information
- Displays user's name and email address
-
Jobs Accepted:
- Job History
- List of all past jobs and its information
- Filter search:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Status: Completed
- Ongoing Jobs
- List of all jobs where parcel picked up and on the way
- Button to mark the job as complete.
- Status: On the Way
- List of all jobs where parcel has not been picked up
- Button to click when the parcel has been picked up.
- Status: Accepted(not picked up)
- Filter search:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Status
- List of all jobs where parcel picked up and on the way
- Job History
-
Jobs Posted:
- Job History
- List of all past jobs and its information
- Filter search:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Status: Completed
- Ongoing Jobs
- List of all jobs where parcel picked up and on the way
- Status: On the Way
- List of all jobs where parcel has not been picked up
- Status: Accepted(not picked up)
- Filter search:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Status
- List of all jobs where parcel picked up and on the way
- Pending
- List of all jobs that have not been accepted by a deliverer
- Filter search:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Job History
c. Job Listings
- A list of jobs available to be accepted
- Filter search:
- Parcel size (small / medium / large / extra large)
- Pick up Location
- Destination Location
- Fragile?
d. Schedule a new job
- A form to fill in the details of the job:
- Parcel size (small/medium/large/extra large)
- Pick up Location
- Destination Location
- Fragile?
- Sender's information
- Recipient's information
- Comments
- Form validation (Required fields)
a. Integrating A Feedback And Rating System For Users:
- Users exchange feedback and provide ratings(From 1-5) for each other based on the job completed.
- Deliverers are able to view sender's past feedback and ratings before accepting the job and after they accept the job.
- Senders are able to view deliverer's past feedback and ratings once a deliverer has accepted their job.
- Users are also able to view their own feedback under view feedbacks in the User Information page.
- Average rating out of 5.
b. Email confirmation:
- A confirmation email will be sent to the user when the delivery has been completed with the job details.
- See Appendix A for more details about this feature
c. Dashboard:
-
Welcomes the user by name.
-
Displaying the current activity: number of jobs ongoing/pending etc.
d. Cancel Job:
- Senders are able to cancel their job if a deliverer has not accepted the job.
e. Additional Job details:
- Each Job's expanded row will contain more information.
- When deliverers accept a job they will be able to view sender's and recipient's name and contact numbers in Jobs Accepted.
- Senders will be able to view the deliverer's name and contact number once a deliverer has accepted the job under Jobs Posted.
a. Form Validation
- Implemented form validation in our schedule job form as well as in our Accept Job modal. Our form validation ensures that users have filled in all the required fields before they are able to submit the form. Additionally we made use of regex for certain fields like postal code and contact number to ensure that users key in the correct number of digits. Contact numbers must start with 6, 8 or 9.
Below are some screenshots:
Accept Job Modal contact number validation:
Schedule Job Contact number and postal code validation:
b. Responsive Design
Our application was styled with responsive react bootstrap components, hence our application is responsive and able to view on mobile devices.
-
Integrating Google Maps API for our Schedule Jobs form. This way users can just key in a keyword or the postal code and their address will be filled up
-
Integrating our own user database to store information about a user. Currently our user data is managed by Auth0, by using our own user database we will be able to store more information about a user (ie contact number and address). This will allow us to extend more features like auto-filling their contact number and address when they are scheduling jobs.
- Implementation: API call to user DB when user logs in. Checks if user is a new user, if new user
-
Notification alert when status of the job changes (eg. when a deliverer accepts a job, when a deliverer marks the job as complete, the deliverer left feedback for the sender etc.) This way users will be notified immediately on any updates to their jobs.
- Implementation: eg. Look into Telegram API to send Telegram message as a notification
-
Payment System to give deliverers extra incentive when helping to deliver a parcel.
Entity diagram
UX Flowchart
1. Tech Stack
Frontend User Interface (Client side):
- HTML/CSS/Javascript (Languages)
- React.JS (Library)
Backend (Server side):
- Python (Language)
- Flask (Python framework)
- MongoDB (Database)
Extras:
- Auth0 - for users to log in to the application and authentication
- GmailAPI - sends an email to the user when delivery is complete
2. Backend API Documentation:
https://docs.google.com/document/d/1C6WGdDMYPHBBic84uD_fXKpEUjGJFxsUaEzFwxNlIE8/edit?usp=sharing
3. Frontend Development:
Auth0:
We decided to use Auth0's services as it can add authentication and authorization services to our application. Auth0 is flexible, secure and scalable. Auth0 is able to provide social connections to other social platforms like facebook, which can be implemented in the future.
ReactJS
We decided to use ReactJS because ReactJS is lightweight, and flexible.
We used npm package manager for JavaScript which is the default package manager for the JavaScript runtime environment Node.js. This allows us to specifically install dependencies required for our project.
Dependencies installed:
- "@auth0/auth0-spa-js": "^1.8.2"
- For login and authentication.
- "axios": "^0.19.2"
- To make API requests (CRUD functions).
- "bootstrap": "^4.5.0"
- CSS Framework for styling components.
- "formik": "^2.1.4"
- For creating forms.
- "react-bootstrap": "^1.0.1"
- ReactJS framework, with components prebuilt.
- "react-bootstrap-table-next": "^4.0.3"
- To implement a table component
- "react-bootstrap-table2-filter": "^1.3.3"
- To implement filter search function with react-bootstrap-table-next
- "react-bootstrap-table2-paginator": "^2.1.2"
- To implement pagination for react-bootstrap-table-next
- "yup": "^0.29.1"
- For validation(form input)
Issues faced:
Auth0:
We had trouble implementing the authorization with the backend to make API requests. Console was showing an error "Uncaught (in promise)" in react-auth0-spa.js, which was obtained from the Auth0 tutorial. This error was caused by including the API audience identifier in our auth_config.json file. However it was strange that the error was gone after a day. We concluded that it could have been an issue with the server on Auth0's side.
4. Backend Development:
Python Flask
We chose to use Python for the backend for ease of future implementation with AI components for a recommendation engine for jobs. We are using Flask for its extensibility and flexibility and it is relatively lightweight compared to django.
MongoDB
We choose to change the database to mongoDB due to ease of use with Python and also flexibility of the documents stored.
Python Dependencies Installed:
- Flask
- To create a backend server for the frontend to call
- Pymongo
- Connection layer between flask server and MongoDB
- Python-jose-cryptodome
- Decoding of JWT returned by Auth0
- See requirements.txt in the folder for packages version information
Prerequisites:
- git
- A Heroku Account
- A Mongo Atlas account
- Heroku CLI (install from: https://devcenter.heroku.com/articles/heroku-cli)
Setting for up deployment:
- Clone repository from https://github.com/mechastriker3/SendIt.git
- Directory Structure (blue = folder, white = files):
- To set up DB
- Login to mongo atlas and create a cluster, inside the cluster create a database and inside the database create a collection called jobs
- To deploy the backend API service:
- Open a terminal
- cd into /backend directory
- Run
heroku login -iand login to your heroku account - Run
heroku config:set DB_USERNAME=<your_db_username> DB_PASSWORD= <your_db_password> DB_NAME=<send_it CLUSTER\_URL=\<your\_cluster\_url - Cluster url highlighted in the example below
- Run heroku create <name_of_your_backend_API>
- Run git push heroku master
- To deploy the frontend UI:
- cd into the /frontend directory
- Run heroku create <name_of_your_app> --buildpack mars/create-react-app
- Run git push heroku master
- Your app is now deployed!!
Basic Testing in Development:
We did basic system testing by using 2 different google accounts to test our application. One account was of a sender and the other was of a deliverer.
The sender schedules the job and the job shows up in the job listing page as well as the jobs posted page and splits according to its status(pending/ongoing/history). We also tested to make sure that a sender cannot accept his own job(instead a cancel job button will be shown as seen in the screenshot below)
As a deliverer, jobs viewed in the job listing page will have an accept job button in the job's expanded row as seen in the screenshot below:
Once a job has been accepted we tested to make sure the status is changed correctly and shows up on the deliverer's jobs accepted page as well as the sender's jobs posted page(ongoing jobs tab). One status change will update the table for both the sender and the deliverer accordingly.
We also tested to ensure that users are able to leave feedback for one another once the job is complete.
System Testing with Users
We did system testing with our advisor Nicholas as well as our mentor Samuel. During testing the features worked as intended, and we took their comments on our design and made some changes to the look and styling of our application.
We also did user testing with friends and family after we have deployed our app and surveyed their experience. Features work as intended and our users mentioned that our application is straightforward and easy to use.
System testing in Mobile
We tested to ensure that all components work properly in mobile and that all components are responsive.
However we encountered certain bugs in the mobile version.
- Options are not displaying as select options in the leave feedback rating input as well as the select parcel size select input.
This was rectified by correcting the option tag in these inputs.
- Third party cookies bug in Safari. Users do not stay logged in when they are routed back to the dashboard (either through breadcrumbs or any link to the dashboard). This causes users to be routed back to the landing page instead of the dashboard. Upon research Auth0 noted that this can happen when browsers like Safari block third party cookies. Safari's ITP technology prevents the transmission of third-party tracking cookies, hence causing silent authentication to fail.
This issue was not rectified. To work around this issue in Safari, we would require a custom domain which only available in Auth0's paid subscriptions. For more information refer to auth0/auth0-spa-js#324 and https://community.auth0.com/t/failed-silent-auth-login-required/33165/24
- Before integration you will need an API credentials file from Google. Follow step one from this link and click on enable Gmail API. This will result in you getting a credentials.json file from Google.
- Clear the folder backend/src/creds (relative to the root folder SendIt) and put the credentials.json file there.
- Run the backend of the app, it should pop open a browser that will prompt you to log in to google. The account that you log in with here will be the account that will be used to send out the confirmation email.
- This flow will only need to happen once. If you need to change the account used to send out the email, delete the token.pickle file in backend/src/creds and run the backend of the app again.
- NOTE: This generation of creds should only be done in development and the creds folder should be securely stored in deployment with proper access permissions set.