Skip to content

Latest commit

 

History

History
191 lines (164 loc) · 11.5 KB

README.md

File metadata and controls

191 lines (164 loc) · 11.5 KB
Raw

PEV-Shop

Personal Electric Vehicle Shop application.

DISCLAIMER: this application is meant for demo purposes only - it does NOT represent a real shop at any moment. Informations about products availability are fake; remaining products informations may be fake or out-of-date. NO purchases will actually be sold NOR delivered, NO payment related actions will be realized - these are only simulated in the application. Please avoid providing any of your real personal informations (like logins, passwords, emails, addresses, payment card's PIN or BLIK codes, etc.) on any of the application's pages or views, including any redirections to external services (such as bank related) - please use fake data anywhere across the application instead. Application's author does NOT take any responsibility for users possible data loss NOR actions made by users.

Table of Contents

  1. Live version and preview
  2. Features
  3. Tech stack
  4. Setup
  5. Tests
  6. API documentation
  7. Development
  8. Credits

1. Live version and preview

The app is available live online: https://pev-shop.scriptychris.dev/.

Below you can watch a brief preview, which presents:

  1. welcome page,
  2. home page,
  3. products dashboard,
  4. chosen products pages,
  5. registration,
  6. mail service,
  7. login,
  8. searching products,
  9. products comparison,
  10. cart and ordering process.
pev-shop-preview.mp4

2. Features

App offers the following features (with ideas to add more):

  • client and seller user accounts:
    • registering,
    • logging in,
    • resetting password
  • searching for products, including a list of recent searches
  • browsing chosen products with their data listed, including gallery, reviews and links to related products
  • listing available products, including:
    • filtering according to alikes: price, category, specifications,
    • sorting and pagination
  • comparing between multiple products
  • adding, modifying and removing products
  • support for mobile, tablet and PC devices
  • making orders for products added to the cart with various payment and shipment methods
  • reviewing bought products

3. Tech stack

React, SCSS, MUI, Webpack, TypeScript, NodeJS, Express, Mongo, Docker, GitHub Actions and Jest logos Cypress logo Formik logo MobX logo

App's frontend is built with React (and partial TypeScript usage). Global state is handled by MobX. Layouts are made with a mix of custom SCSS and Material-UI. Forms are created with Formik. Products shipment via parcels is possible due to InPost's Geowidget. Frontend is bundled with webpack.

Backend is written on Node.js in TypeScript, with middleware based on Express.js (supporting Rest API) and database created with MongoDB (using Mongoose as ODM). Authorization is implemented via JWT and custom user roles system. Emails to users are send via Nodemailer and hosted with MailHog. Payments for ordered products are handled by integrated PayU API.

The app's database and middleware are covered with unit tests created with Jest. Whole-feature focused scenarios are covered by end-to-end tests created with Cypress.

Whole app is containerized via Docker, which helps with easier setup and executing end-to-end tests. Repository is hooked with GitHub Actions CI/CD for integration purposes.

4. Setup

Regardles of setup method, the app is locally served on http://localhost:3000 by default.

Automatic setup

Whole app can be bootstrapped with Docker.

  1. Create .env file based on .env.example.
  2. Navigate to ./docker folder with command:
cd docker
  1. Start Docker (if your Docker setup requires sudo access, you may be prompted to type your password):

NOTE: installation downloads and processes a few GB of data, so it may take a while.

sudo docker-compose --env-file ../.env -f docker-compose.yml -f docker-compose.app-standalone-volumes.yml up

This will install all necessary dependencies, populate database with initial data and serve the app.

Manual setup

Manual database setup

Database has been created using MongoDB v4.2.0 with mongodb v3.5.10 and mongoose v5.9.27 NPM packages.

To install MongoDB database locally, please download and install it on your machine from this URL: https://fastdl.mongodb.org/win32/mongodb-win32-x86_64-2012plus-4.2.9-signed.msi (you can skip first three below steps then) or follow these steps:

  1. Go to https://www.mongodb.com/try/download/community
  2. Choose "MongoDB Community Server" tab
  3. Choose latest 4.2 version from "Available Downloads" section and download it
  4. Install database by following the setup program
  5. Create data folder inside project's database folder (NOTE: database/data folder is set to be ignored by Git)
  6. Start the MongoDB running the following command (i assume you are using Windows with default installation path - if not, please adjust the path accordingly) C:\Program Files\MongoDB\Server\4.2\bin\mongod.exe --dbpath="absolute_path_to_project_root\database\data"

In case of any issues, please refer to the official MongoDB installation guide for your operating system [Windows / Linux / macOS].

Manual email service setup

The app is integrated with MailHog email service, which you can install from it's repository. By default, this service's website is available on EMAIL_WEB_HTTP_PORT 8025. You may need to change EMAIL_INTERNAL_HOST env variable to localhost, if you want to use your system's MailHog instead of the instance from Docker.

Manual app setup

The app building process is based on Node.js v14 LTS and npm, so after installing it (optionally via NVM) do the following:

  1. Install dependencies by command:
npm ci
  1. Build project:
npm build

  1. Create .env file based on .env.example. Change DATABASE_HOST variable in .env file to localhost value.

  2. Serve the app:

npm serve

5. Tests

The app contains unit and end-to-end tests. You can run them as following:

  • unit tests:
npm run test:unit
  • end-to-end tests:

NOTE: it requires Docker installation and DATABASE_HOST variable in .env file set to pev-db value.

npm run test:e2e:dev

6. API documentation

API docs are generated by TypeDoc, which output is grouped into a few folders.

7. Development

If you would like to play with the application's code, package.json file contains helpful NPM commands, for example:

  • populate database with default initial data and included cleanup (in case you would like to reset database state)
npm run populate-db
  • develop frontend with React's hot module replacement
npm run dev:frontend
  • develop backend with automatic ad-hoc builds
npm run dev:backend
npm run debug
  • generate API documentation based on current source code (with restriction to files listed in grouping script)
npm run generate-api-docs

8. Credits