Skip to content

Latest commit

 

History

History
409 lines (269 loc) · 24.5 KB

README.md

File metadata and controls

409 lines (269 loc) · 24.5 KB
Raw

Open Source Love MIT Licence

project readme background

Pandemic neighborhood delivery service for social good ♥️

Short demo here

Table of contents 📚

About Our Online Shop 🚚

Welcome to our Seattle produce delivery shop!

During the ongoing pandemic, getting groceries can sometimes be a real challenge. The scarcity can go beyond delivery time slots. Items you order can run out of stock before being delivered, and if you venture to the store, you may find slim pickings in some aisles.

It all started out a few weeks ago, when several people in our Seattle neighborhood decided to organize a no-contact delivery service to help people in need. We noticed that some of our friends or family members find it challenging to go out to shop, either due to shortage of mask supplies or health reasons. Most of them were worried about their safety, and whether they were able to always get the goods that they wanted if they went out to shop. Understanding their concerns, we decided to start this non-profit community service and deliver the produce to people's doors without any charge. We currently have around 5 people in our neighborhood as our regular customers.

The website is our next phase of expansion. We are planning to contact wholesalers in the greater Seattle area and directly order products from them. This would save us more time to order and fetch the products. It will also open up a broader variety of quality produces for the customers. We are planning on using this website as a platform for customers to order goods directly.

Features

  • Located in the greater Seattle area 🌴💦
  • Fully functional produce delivery shop with more than 50 items available
    • 5 main categories: vegetables🥬, fruit🍋, protein🍗, seafood🍤, dairy🧀
  • Signin, signup, and signout functionalities, including Google signin
  • Secure checkout and payment using Stripe services
  • Admin page that handles user orders as well as product management
  • Covid glimpse that displays useful current covid-19 information

Tech-stack

  • Frontend: React & Redux
  • Backend: Node & Express
  • Database: MongoDB & FireStore
  • Authentication: Firebase
  • Payment: Stripe API
  • SEO: currently in development process
  • Testing: currently in development process

Open-source Team

Our shop platform is an open-source project, and we are always looking for more like-minded developers who would like to contribute! These are our current contributors helping push the project forward each day.

Hans Easton - Organizer/Developer


I am Hans. I am currently pursuing a computer science major at University of Washington. I am really excited to build up this website using my programming skills, and I am even more excited to collaborate with other amazing developers to contribute to something meaningful.


Mayank Pandey - Developer

I'm an international student at the University of South Florida pursuing a Bachelor's degree in Computer Science. I have completed an independent web development course from Udemy which has allowed me to work on some of the most exciting projects. As a developer, I'm wildly enthusiastic about coding, problem-solving, and software development. I am always ready to learn to grow professionally in this field.

Andres - Developer


I am an Estonian psychologist turned analyst, trying to turn into a full-stack developer. For a while I tried to avoid going into the tech world because it seemed removed from actual human interaction, but realised it is a lot of problem solving which often involves a lot of teamwork. I am studying on my own and trying to make worthwhile open-source contributions!

Bryan - Developer


I am Bryan a developer from New York who is very passionate about tech! Currently, i am contributing to open-source to collaborate with other developers and to gain more skills. My goal is to become a professional FullStack developer!


Join our open-source project! 💪

Motivation for open-source

This is a beginner-friendly open-source project aimed for social good. We are always looking for more passionate programmers, like you, to contribute!

Open-source project is powerful because it lowers the barriers to adoption and collaboration, allowing people to spread and improve projects quickly. It also is a perfect place for anyone to hone their programming skills and share their visions and ideas with like-minded others. Here are three major reasons as to why you should contribute to our open-source project!

  • Collaboration: Open-source project can accept changes from anyone in the world.
  • Adoption: Open source project can be used by anyone for nearly any purpose.
  • Transparency: Anyone can inspect an open source project for errors and making small and big improvements.

If you are still confused about the concept of open source and would like to learn more, check out the Github's official guide!

Coding for social good

I am a firm believer that a personal project is so much more meaningful if it brings positive impact to the society.

I have always been in awe of people who strive to make a change in the world. The philanthropists and activists on the television, in interviews, and in books inspire me with their radiating passion for what they stand for, and I used to hope that one day I could be passionate enough about something to also create change in the world.

And now, here I am, launching the first open-source project here on Github. This is an opportunity for people to connect with others who share the same drive for creating positive changes around us.

It can be overwhelming

I remember the first time I tried to make contribution to an open-source. The experience was quite overwhelming. There were so many things I did not understand about the project, and I couldn't even understand the command lines that were used for setting up the project.

Even now, I am by no means an experienced programmer. There's still so much I am learning everyday. I started programming about two years ago, and it has been a challenging yet exciting journey. One of my regrets I had along the way was failing to discover the beauty of contributing to an open-source. Somehow in my mind, I always thought that I need to be an experienced developer to be able to contribute. But THAT IS TOTALLY NOT THE CASE. All you need is a heart to contribute, a willpower that drives you forward, even after failure, and a faith that you will succeed if you keep at it.

I want to make sure your experience here is a positive, friendly, and exciting one. Together we can foster a loving community for developers.

Join us!

I started this project in hope that the delivery service will not simply be limited to our Seattle neighborhood, but rather anywhere else in the world. ♥️

Long before the idea of creating an open-source project even came to my mind, there were already kind-hearted people who were offering such services to others in need in the neighborhood. So even without our online shop in place and out there ready to serve, you can do something for your community right now, regardless of where you are! 🎉

With that said, I would really really encourage you to fork and use this project in whatever way you want. Feel free to redesign it in your own language, for your own neighborhood . Let's keep spreading love during this challenging time.

Once you join our project and make your first contribution, we will list you as one of our contributors and add your profile in our README.md section. I truly believe that working on an open-source project will make you a better programmer and communicator, and it will also give you something meaningful to talk about when you talk to a recruiter (if you are going to industry in the future)!

Whether it is because of your passion for social good, or your desire to hone your web programming skills, or simply to find an opportunity to gain some experiences programming with others, we would love to have you.

  • Our slack server is coming up soon!
  • If you have any hesitations, questions, or concerns. Feel free to send me at email. Happy to connect!

Project Setup 🚀

Now that you've made your decision to make your first contribution. Here's how to set it up.

Structure Overview

.
├── assets                      # public resources & assets
├── client                      # handles all of the frontend logics
  ├── assets                    # storing svg files
  └── components                # where React components live
  └── pages                     # where main shop pages lives
  └── firebase                  # handles firebase connections and logic
  └── redux                     # handles all redux logic, sets up redux store
  └── app.js                      # main entry point of the front end app
├── server                      # (root) directory handles all of the backend logics
  └── models                    # product and checkout item model for database
  └── routes                    # route handler for API endpoints
  └── app.js                    # main entry point for all requests
├── LICENSE                     # MIT license
└── README.md                   # documentation of the shop project

General Setup

  1. Fork and clone the project.

  2. Use your favorite text editor

    • Personally I use VScode. You are welcome to use any of your preferences!

  3. From the root directory of the project, install dependencies with npm

  4. npm install    // install dependencies of backend
cd client   // navigate to the client directory
npm install    // install dependencies of backend

  5. Configure the appropriate environment variables

  6. Running only the frontend

    • This means that you will be able to run the website locally without most of the shop features. Since all of the produce information are fetched from the backend server, you won't be able to access any of the produce, thus the shop page will be listed as empty. If you have not set up the Google firebase, your sign-in and sign-up page also will not be functioning. However, you can use this if you are only interested in changing the styles of frontend compoennts.

    From your root directory:

      npm run client

    Visit the frontend application in your browser at http://localhost:3000

    • Note: your frontend server will hot reload whenever you save on a file, a feature of React

  7. Running frontend and backend

    • This will give you access to the entirety of the application. Note that you need to set up the Google Firebase and prepopulate products using the Admin page in your application before being able to use the products in the shop page.

    From your root directory:

      npm run dev   // you can change the command in package.json, but don't push it to Github

    This will spin up both your frontend React and backend Express server.

    • Visit the frontend application in your browser at http://localhost:3000
    • Your backend server is listening on port 5000

Configuring Project

.env file on the backend

On our backend, our application uses MongoDB to store produce-related information and the Stripe API to process user payments. Note that even though the user payment's logic is set up on the back-end, you won't be able to process payment in the shop checkout page, since the application has not reached the deployment process.

Our application uses environmental variables to manage configuration for both MongoDB and Stripe on the backend. These values are set in a .env file in the project root directory that SHOULD NOT BE PUSHED TO GITHUB for safety reasons. Each developer *should set up their own account's connection string on their own local machine instead.

We have provided you with an example of .env file in the root directory.

To set up a .env, copy the .example.env file, which lists needed configuration values. For example, in the Mac OS terminal:

cp .example.env .env

A set variable in the .env file will look like this:

mongooseConnection='your own connection string'

Change the 'your own connection string' to your own mongooseConnection string. You will need to create a user account at the MongoDB website, set up a free cluster as well as database, and find where the connection String is for your cluster. It should be easy!

Repeat the same process for the Stripe API. You should replace the placeholder with your own Stripe API secret key. If you will be working on code that is not related to the payment functionality, you can safely ignore this part.

If you need to introduce a new environmental variable, please coordinate with Hans. Make sure to add it to the .example.env file, and note it in your pull request.


### configuring frontend

There are two files you need to configure before being able to run the application.

Firstly, make sure you have signed in firebase and created a new project for the application. Log into your firebase console and configure the following setting for user signin and authorization.

You are provided with a folder called config that has all your keys

client/src/config/

  1. rename firebase_key.example.js and stripekey.example.js to firebase_key.js and stripekey.js

  2. go to https://console.firebase.google.com/project/<YOUR_PROJECT>/overview to get your sdk key copy paste into config within the firebase_key.js file

  3. go to https://dashboard.stripe.com/ click on developers and click on api key copy and paste Publishable key in STRIPE_PUBLIC_KEY

Congratulations! 🎉🎉🎉 You are done with all of the project setup! Now you can test out whether your configuration is correct by running the project. You should now be able to access all of the project's functionality.

(Note: the configuration process feels a little cumbersome right now. We hope to put all of the configuration setup into .env file in the future to make the process a little easier. If you would like to make this happen, please check out this issue!)

Understanding User Authorization ✔️

In our current shop setup, users are able to log in and log out. Users are able to sign in with their Google account directly. Alternatively, they are also able to sign up using their personal email address and password.

We currently have two types of users: admin user and normal user.

  • The normal user is able to access the general functionality of the shop, including adding items to cart and checking out.
  • The admin user is able to access the admin edit-product and admin checkout page that are inaccessible to normal users. In particular:
  • Admin edit-product page enables you to add new products (with relevant product information) to Mongo Database. Other users will be able to see the new product once they refresh the page.
  • Admin checkout page keeps track all of the successful orders made by the all of the users. We use this page to know what products users have ordered in preparation for our delivery process.

Note: The admin pages are still in development process (basic functionality already implemented). Help us make them better!

User Authorization in Code

Our shop's signin logic is mostly handled by Firebase. In our client/src/components/App.js, the function onAuthStateChanged is an observer function defined by Firebase that is triggered whenever a user signs in or signs out.

// Once the user's authentication status is changed
auth.onAuthStateChanged(async (user) => {
  if (user !== null) {
    const userRef = await createUserProfileDocument(user, [false]);

Note that in the function, we are calling a function called createUserProfileDocument. This function captures the user's information and stores it back to our firebase database, so that next time a user signs in, we are able to verify their identity.

In particular, notice that the second parameter of the function is an array containing a boolean value. The value determines whether the user passed in will have the admin privilege or not. Normally, the default is false, since we don't want to grant a user the admin privilege.

In the case when you want to grant a user privilege (e.x. for your personal account), follow the following steps:

  • make sure you have set up the connection for firebase
  • run the server using npm run build
  • change the parameter [false] to [true] in createUserProfileDocument indicate you want the admin privilege for any incoming account registration
  • register a new email account (either through google signin or normal signup, but make sure the account doesn't store in the database) using the application:
  • go to your firebase console and make sure your user entry in the cloud firestore collection users has the privilege field set to true
  • reset the parameter from [true] to [false] in your client/src/components/App.js

Now, you are able to render components conditionally by checking the user's privilege. For example, like this:

  <Route
    exact
    path='/admin/add'
    render={() =>
      !user || !user.privilege ? (
        <Redirect to='/' />
      ) : (
        <AdminAddProductPage />
      )
    }

We are checking whether the user is signed in (!user) and whether the user has admin privilege (!user.privilege) to determine rendering or redirecting.

Finally, make sure you set your email address to be an admin account using the steps above. Only then will you be able to add products to the database via admin-edit-product page ♥️.

Adding products

Right now, your application should run ok! You should be able to log in and log out, and you are able to access all of the pages. However, notice that the shop page is all empty. This is because there's no produce stored in the database. Now it is time to add in some products!

First of all, make sure:

When you spin up the application, you should see the shop page look like the following:


In the navbar, click on the admin tab. It should bring you to the following page.


Now, simply type in the relevant information. Here are a few things to note:

  • None of the fields should be left empty

  • The image url needs to be a valid image link, like this

  • The product type needs to be matching with one of the following

    • vegetable, poultry, dairy, seafood, fruit (case insensitive)
  • A pop-up window should appear when you click the "save" button. If everything goes well, you should be able to see the product you have newly added in your shop page when you refresh the page! Otherwise, the pop-up window should display the error message.
  • Our shop currently does not support editing the product, as well as deletion. We will continue to work on these functionalities as they are crucial. If you want to do these operations as of right now, you would need to directly go to your MongoDB console and modify your database content.

Stripe checkout

Since our project is currently in the development process, the stripe checkout is only valid for test checkout.

WARNING: PLEASE DON'T ENTER YOUR PERSONAL CREDIT CARD INFORMATION!!

Instead, if you want to test out the stripe functionality, you can use the dummy card information provided by Stripe.

  • The card number is 4242-4242-4242-4242
  • The exp date can be any date after the current date as you are typing it.
  • The CVC number is any 3-digit number.
  • Do not use the 'Remember me' option.

Since this is pretty important, someone might want to add a line of warning at the bottom of the checkout page. Here's the issue if anyone likes to add work on it!

After you have successfully made the test payment, you should see a pop-up window that displays Your payment is successful. We will be in touch through email soon. Now, all of the products a customer has checked out and paid for has been added to the MongoDB database (feel free to check yourself)!

Cool! Keep hacking!! 🎉

Contributing 💦

The previous parts help you set up the project. Please refer to the CONTRIBUTING.md if you would like to take a further step to contribute!

Also check out the issue guideline here!

Help us refine the README documentation here in this issue!

Special Thanks ❤️

Some of the project structure and technical knowledge are made possible by the awesome Udemy course instructor Andrei and Yihua. A huge thanks to both of them! ☺️

License 📝

See the LICENSE file for license rights and limitations (MIT).