Our web app provides a online tech shop for users around the world to be able to buy the latest gear with the best reviews at the best prices. We aim to provide the best buying experience, with nice to have features such as support messages, PDF invoices, email confirmations, stock alerts and much more.
- Inés Alonso Izquierdo - [email protected] - Github: tsukii14
- Santiago Arias Paniagua - [email protected] - Github: 4rius
- Ignacio Canículo Domínguez - [email protected] - Github: nachocaniculo
- Ángel Covarrubias Roldán - [email protected] - Github: Angelcova
- Andreas Wolf Wolf - [email protected] - Github: Andreas4122002
Entities
| Entity | Description |
|---|---|
| Users | People that will be using our web app. There will be four types of users which will be explained below. All users can edit their profile, and details, including an image. |
| Products | Our users will be able to add these products to their shopping carts and wishlist. They will all have a description, an image, and different reviews. The administrator will also be able to check the stock. |
| Purchase history | Users will be able to check their purchase history, with the timestamp of the purchase date, hour and payment method, along with the shipping address and price details. Users will be able to generate PDFs from each purchase so they can have access to their invoice. The administrator will be able to access the whole purchase history of the webpage, including details like who made the purchase. |
| Reviews | Products will have reviews, and these reviews will be added by the users that previously bought the product. Each review will contain a five star rating, along with a comment, and the possibility of adding images. Only users who have bought the product will be able to add a review. The review will be published inmeadiately after sending it, but the administrator will be able to take it down if it contains harmful or inappropiate content. |
| Support messages | Each user will be able to send support messages, these messages will be stored on our database, and any support personnel will be able to answer the query, this messages will be kept for as long as the query is active and will be removed after a qeury is marked as resolved by either a user or a support agent. |
Users and their permissions
| Entity | Description |
|---|---|
| Admin - Site owner | This user will be able to add new products, manage stock and purchases and remove products, as well as moderating reviews. This entity owns the whole website and can make changes to any other entities excluding support messages, which are only owned by support agents and users. |
| Support | These users will see and answers all complaints from the registered customers. These users won't be able to make purchases, use the cart or the wishing list, they will be able to browse the web as usual but their actions will be limited to replying to customer queries. They own the support messages entity, and they can manage their own profile |
| Registered customer | These users will be able to make purchases, add products to a wishlist, use the shopping cart, add reviews (they will also be able to delete their own reviews), view their purchase history, generate invoices and contact support. They own their own entity and can modify their user as much as they want, they can also modify the support message entity, marking a query as solved, or creating one, adding a new table to the database. |
| Guest | These users will be able to browse the whole website, but their reach will be limited and they won't be able to make purchases, contact support, or have any wishlist. They will be able to have a shopping cart which they will preserve if they register later. They won't own any entity and won't be able to modify any entity. They are only allowed to create a new user entity, registering on our website. |
Images
| Entity | Description |
|---|---|
| Users | This entity includes the user profile picture, this image can be uploaded by the user |
| Products | The products will contain one or more pictures of the product we are selling, these pictures can only be uploaded by the administrator. |
| Purchase history | The purchase history will contain a thumbnail of the product the user bought, this will be the same image as the product's main image |
| Reviews | Users adding reviews will be able to upload up to 3 photos of the product, no one will be able to change these photos once the review is submitted. |
Charts
Our web app will include 2 types of charts, the first one will be available for anyone, it will be a price history chart and it will be shown on each product, this is a type of line chart. The other chart will be a bar chart showing the quantities sold each day for the last week for the administrator.
Complementary technologies
- Invoice generator: Each user will be able to download a PDF invoice of their purchases.
- Automatic emails: Users will receive notification emails when they register and when they make purchases on our website.
- Stock notifications: Users will be able to receive a notification on the website when they toogle the let me know when there's stock button on our out of stock products.
- Support notifications: If a support agent replies to a customer, this customer will have a notification on his dashboard.
- Use of Google Maps for the user to be able pin point his location, avoiding the trouble of inputting all the address details.
Algorithm
The algorithm used on our web app will be a simple recommendation algorithm, which will recommend products to our users while they are browsing our web page, according to different factors like their history, their wishlist, their recent purchases or their cart.
Screenshots
We have developed all our pages from scratch using Bootstrap, if everything works out as planned, our model should be completely responsive, as we have used Bootstrap's grid system. But we will have to start developing the web app itself to know if the model is really responsive.
We aim to provide a simple, yet enjoyable, shopping experience, with a few featured items running on a carousel in the middle of the website, as well as some recommendations beneath it, we aim to have at least 2 rows of products, but this is just the model.
Login
A simple login page for the user to be able to authenticate, this allows the administrator and the support agents to login as well
Sign up
Another simple sign up page, where new users can sign up. Administrators and support agents have to be manually added into the system, so they won't be able to sign up using this form
Purchase history
Our website will let the user know all the purchases he/she has done, as well as getting further assistance, leaving a review, returning the product, or cancelling an order that has recently been made. This history is similar to the one that will be accesible for the administrator. We will also provide a unique ID for each order.
Add review
Our users will be able to leave reviews that include a title, a comment, and some photos
Product view
A view where clients can check out photos, specifications and reviews on a product. They will feature a review, and the rest of them will be available before. Note that this is just a model, and our products will include all their information in English.
Confirmation
A simple message confirming a purchase providing a unique identifier
Error
A simple error page
Checkout
An easy checkout for users to complete their purchases
Shopping cart
Clients will be able to add quantities and get errors if there is no stock left, as well as continuing to checkout
Search results
How we plan our products to be displayed when a user performs a search
Review history
How the administrator will be able to moderate reviews
Edit profile
The user will be able to change anything on its profile
Add produtcs
The administrator will be able to upload new products, that will become available for everyone browsing the website the moment the form is submitted. We will add the option to add "tags" so the recommendation algorithm can start rolling out the product to select clients.
Edit product
The administrator will be able to access this tool to update the product's price, as well as name, description, photos...
Support messages
Users will be able to chat live or leave a conversation opened with a support agent on their messages tab
Admin dashboard
A set of tools for the admin to be able to track the progress of the website, as well as editing and adding products, and modding reviews. The administrator will also be able to access a graph that will show the number of orders that were created the last week.
Diagram
The diagram shows how the user will be able to move throughout our website, all the screenshots can be found on the tab before, as the diagram was not comprehensible using thumbnails, as our website includes several administrator tools and other features that made it impossible to read.
The navigation is as we established on the previous phase, with minor tweaks, for example, we figured agents should be able to use their account to buy products, and the admin shouldn't have access to the shopping cart, as it would be nonsense for him to buy products. We believe the roles are clear enough, we allow the users and agents to buy products, and the admin to manage the website. All the features in between are available for all of them, as long as they are not related to the purchase of products. The anonymous user will be able to access the home page, the login page, the sign-up page, the search results page, the product page, and he will need to log in to access the rest of the features.
Our website has suffered some changes, without deviating too much from the design we initially proposed, our main pages now look like this:
Home page
Anonymous home page, the user can access the login page, the sign-up page, the search results page, the product page, and he will need to log in to access the rest of the features.
Logged-in user, his featured offers are tailored to the products he has bought in the past.
Search results page
The search results page has been updated to include the load more button using AJAX.
Product page
The product page has been updated to include the add to cart and wishlist button, and the reviews section. The logged-in user can now add products to his cart and wishlist, and he can also leave reviews to products he has bought. Logged-in users can see the profile picture of the user that left the review, as well as the images of it. Anonymous users can only see the email of the user that left the review, and the review itself.
Shopping cart page
The shopping cart page has been updated to include the remove from cart button and the checkout button.
Wishlist page
The wishlist page has been updated to include the remove from wishlist and the add to cart button.
Recent orders page
The recent orders page now works, and lets you return products, add reviews, contact support and download the invoice in PDF format.
Invoice
The invoice is now available in PDF format, and it includes the product, the total price, the shipping address, the date of the order, and the order number.
Support chat
The support chat now works, and lets you chat with the support agent, and leave a conversation opened.
Admin dashboard
The admin dashboard is new, and includes a set of tools for the admin to take a look at the progress of the website, as well as edit and add products, check price history, and mod reviews.
The admin dashboard uses AJAX to load more products.
Price history
The price history chart is new, and it shows the price history of a product, and it includes a button to download the chart in PNG format. For now, it is only available for the admin, but we plan to release it for the users and agents as well.
Profile
The user can now change everything on his profile except for his email. He can't manually change his password from here, but can recover it using the forgot password feature.
Active support messages
The active support messages page is new, and it shows the people who have stared a conversation with the agents, any agent can access any conversation and reply to it. They are ordered by timestamp, and the most recent conversation is at the top.
We provide instructions to build and run a complete .jar package including all the necessary dependencies, as well as running the web app from an IDE or from the command line.
Note: We don't provide instructions to build a .war file, as we believe that the .jar file is more convenient for this project as we don't need to deploy it on a server, and we will use Docker when we deploy it on a server anyway.
For this guide to work, you need to have the following installed:
- Java 17 (We use Corretto 17, but any other OpenJDK 17 distribution should work, we use Corretto because Amazon provides it, and it's a trusted source)
- Maven (We recommend installing it from your package manager (brew, pacman, apt), or let your IDE do it for you)
- Git (You can also use the GitHub Desktop app)
- Access to our database (We will provide the credentials, URL, ports and allow the IP addresses of the machines that will be accessing the database)
- Access to a terminal
- Access to a web browser (We have tested Firefox and some Chromium based browsers, it should work on anything)
- Access to our GitHub repository
Optional:
- IntelliJ IDEA Ultimate
- VS Code
- MySQL Server (We use an Azure MySQL database as it was more convenient for us, but it works on any MySQL server)
We use Azure's MySQL database as it was more convenient for us than having to deploy lots of objects when testing the ajax buttons, or other features, plus it has allowed us to save time redeploying it each time we had to test, or adding lots of products, allowing us to store them indefinitely. This was free as part of our Microsoft Azure Subscription.
Either way, we provide a SampleDataService.java file that creates 3 products, 3 users and a review, for basic testing it might come in handy, however, to test our web app and get a glimpse of what it looks like with more products, we highly recommend running it with our database. The credentials can be found under application.properties, and we can provide access to the IPs that will be running the app
Setting up a database (Not recommended)
-
Install MySQL Server
-
Create a database with a schema called
3techmarket -
Change the commented lines in the
application.propertiesfile to match your database's credentials and comment the lines that connect the actual Azure database.
-
Uncomment the @PostConstruct method in the
SampleDataService.javafile
-
Run the web app, and it should create the tables and populate them with the sample data
Building a .jar using mvn and running it from the command line (recommended)
- Clone the repository:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git - Navigate to the project's root directory:
cd webapp11/backend/app, this is where thepom.xmlfile is located - Build the .jar file:
mvn clean package- If everything goes well, you should see something like this:
- If everything goes well, you should see something like this:
- Run the .jar file:
java -jar target/app-0.0.1-SNAPSHOT.jar - Go to
https://localhost:8443/to see the web app running - To stop the web app, press
Ctrl+Con the terminal
- To run the web app in the background, run
java -jar target/app-0.0.1-SNAPSHOT.jar &instead of step 4 - To stop the web app, run
kill $(lsof -t -i:8443)on the terminal- To run the web app on a different port, run
java -jar target/app-0.0.1-SNAPSHOT.jar --server.port=XXXXinstead of step 4, whereXXXXis the port you want to use, we use 8443 because it's the default port for HTTPS when using Spring Boot in development mode. - To stop the web app, run
kill $(lsof -t -i:XXXX)on the terminal, whereXXXXis the port you used to run the web app
- To run the web app on a different port, run
Running the app from an IDE (easier)
We recommend using IntelliJ Idea Ultimate, as it's the IDE we use to develop the web app, and it's the one we're most familiar with, but you can use any IDE you want, as long as it supports Maven projects.
Using IntelliJ Idea Ultimate
-
Open the project in IntelliJ Idea Ultimate, clone the repository if you haven't already:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git -
IntelliJ will automatically detect the project as a Maven project, and will ask you if you want to import it, click on
Import Maven Projects -
Once the project is imported, navigate to the
AppApplication.javafile, located atbackend/app/src/main/java/com/techmarket/app/AppApplication.java -
Right click on the file and click on
Run 'AppApplication'
-
Go to
https://localhost:8443/to see the web app running -
To stop the web app, press the stop button in the top right corner of the IDE or on the bottom left side of the console
-
If your IDE is properly configured, you can also run the web app from the top right corner of the IDE, by clicking on the green play button next to the
AppApplicationclass
Visual Studio Code
This steps assume you have the Java Extension Pack and the Spring Boot Extension Pack installed on Visual Studio Code.
-
Open the project in Visual Studio Code, clone the repository if you haven't already:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git -
Navigate to the
AppApplication.javafile, located atbackend/app/src/main/java/com/techmarket/app/AppApplication.java -
The editor should show a
Runbutton above themainmethod, click on it (you can also press the Play button in the top right corner of the editor assuming you have the Spring Boot Extension Pack installed)
-
Go to
https://localhost:8443/to see the web app running -
To stop the web app, press the stop button in the floating menu bar that will appear at the top of the screen, or press
Ctrl+Con the terminal
Running the app from the command line (faster)
- Clone the repository:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git - Navigate to the project's root directory:
cd webapp11/backend/app, this is where thepom.xmlfile is located - Run the app:
mvn spring-boot:run-
If everything goes well, you should see something like this:
-
- Navigate to
https://localhost:8443/to see the web app running - To stop the web app, press
Ctrl+Con the terminal - To run the web app in the background, run
mvn spring-boot:run &instead of step 3 - To stop the web app, run
kill $(lsof -t -i:8443)on the terminal
- To run the web app on a different port, run
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=XXXXinstead of step 3, whereXXXXis the port you want to use, we use 8443 because it's the default port for HTTPS when using Spring Boot in development mode. - To stop the web app, run
kill $(lsof -t -i:XXXX)on the terminal, whereXXXXis the port you used to run the web app
Entity Relationship Diagram (ERD)
Please bear in mind that many of the relationships represent lists, our database may appear like we have lots of entities, are actually just one entity with a list of objects. Some of the relationships overlap on the diagram, to read the diagram, please follow the arrows and read how the entities are related, comparing the diagram with the code will help you understand it.
Class and templates diagram
All members have contributed to the project in a similar way, and all members have worked on all parts of the project, this table is just a rough estimate of the amount of work each member has done.
| Member | Contributions |
|---|---|
| Santiago Arias | Spring security - All AJAX request buttons - Cart - Purchase history - Image handling - Product search - Automatic emails - Support messages - Entities - Add reviews - Database Handling |
| Andreas Wolf | Checkout - Wishlist - Edit profile - Edit product - Admin dashboard - Entities - Spring Security -Database setup - Database Handling - Repositories |
| Ignacio Canículo | Add product - Price history chart - Email password recovery - Login - Signup |
| Inés Alonso | Product details - Review handling - Image handling - Thorough testing |
| Ángel Covarrubias | Recommendation algorithm - Home page - Thorough testing |
Santiago Arias
Andreas Wolf
Ignacio Canículo
Inés Alonso
Ángel Covarrubias
Santiago Arias
Andreas Wolf
Ignacio Canículo
Inés Alonso
Ángel Covarrubias
If you use our database you can use the following credentials to log in
- ADMIN: [email protected] / 12345678
- USER: [email protected] / 12345678
- AGENT: [email protected] / 12345678
If you use the SampleDataService
- ADMIN: [email protected] / admin123456
- USER: [email protected] / user123456
- AGENT: [email protected] / agent123456
As we are using SpringBoot 3, we need to use need to use springdoc-openapi v2.0.4 to generate the documentation. The documentation is available at /api-docs and /v3/api-docs endpoints. We also created a Postman collection to test the API.
We provide a Yaml file with the API documentation, and a html file with the generated documentation that were made using springdoc-openapi-maven-plugin 1.4 to get the Yaml file and openapi-generator-maven-plugin to generate the HTML. You can find them on this raw YAML file and HTML file.
You can also access and test the API using the built-in Swagger UI provided as part of the dependency at https://localhost:8443/api-docs, as well as the YAML file at https://localhost:8443/v3/api-docs.yaml.
To create the documentation yourself you can expand the following section.
How to generate the documentation
-
Disable anything that has to do with https in the
application.propertiesfile (uncomment the following lines):
This will make the app start in http instead of https.
-
Uncomment the following lines in the
pom.xmlfile (both plugins):
-
Run
mvn verifyto generate the documentation
Notes: You should run the command from the root folder of the project -> app. If you run it from the backend folder it will not work. The provided documentation is already up-to-date, so you don't need to generate it again. Remember to comment the lines you uncommented in the pom.xml file and uncomment the lines you commented on the application.properties file.
We provide 2 docker_compose.yml files, one of them connects with our Azure database and contains lots of sample data the other one connects with a local database using the MySQL official Docker image. You can choose the one you want to use. You can add some sample data using the SampleDataService.java file.
If you don't have the image created, it will automatically be pulled from Docker Hub (it will pull the version tagged latest). The image is available at https://hub.docker.com/r/4rius/threetechmarket. This image was built on OS linux/arm64/v8 (Apple Silicon), so it might not work on other OS, you can create your own image using the Dockerfile provided in the root folder of the project, or using the create_image.sh script for convenience.
Using a local database (MySQL Docker image)
- Install Docker and Docker Compose
- Navigate to the
dockerfolder - Run
docker-compose up -dto start the containers (they are configured to wait for the database to be ready)
If you want to stop the containers run docker-compose down and if you want to remove the images run docker-compose down --rmi all and if you want to remove the containers run docker rm -f $(docker ps -aq) (this will remove all the containers)
You can also stop a container with docker stop <container_id> and remove it with docker rm <container_id> where container_id can be either threetechmarket or 3techmarket_db
You can also run docker-compose up to see the logs of the containers
You can check the status of the containers with docker ps
If everything is ok you should see 2 containers running (database and application):
Using our Azure database
- Install Docker and Docker Compose
- Navigate to the
dockerfolder - Run
docker-compose -f docker-compose-azure.yml up -dto start the containers (only one container is needed)
If you want to stop the containers run docker-compose -f docker-compose-azure.yml down and if you want to remove the image run docker-compose -f docker-compose-azure.yml down --rmi all
You can also stop the container with docker stop threetechmarket and remove it with docker rm threetechmarket
You can also run docker-compose -f docker-compose-azure.yml up to see the logs of the containers
You can check the status of the containers with docker ps
If everything is ok you should see 1 container running:
We provide a handy shell script to easily build and image of our app and be able to run them, however, you can manually create the image as well, but you won't be using dockerized Maven or JDK, so you will need to have them installed on your machine.
The provided shell script has been tested on Apple Silicon Macs and x86 Linux
- Clone the repository
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git - Navigate to the
dockerfoldercd webapp11/docker - Run
./create_image.shto build the image - Refer to the instructions above to run the image
The image name is 4rius/threetechmarket and the version is 1.0.0 (also tagged as latest)
If the bash script fails to run you may need to give it execution permissions with chmod +x create_image.sh
Deploy the application to Railway through the command line (NOT WORKING / NOT TESTED / NOT REQUIRED)
- Install the Railway CLI with your package manager of choice (brew, apt, etc.) (Example for macOS:
brew install railway) - Login to Railway with
railway login - Clone the repository
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git - Navigate to the project folder
cd webapp11 - Create a new project with
railway init - Link the project with the current folder with
railway link - Add the MySQL plugin with
railway addand select the MySQL plugin - Run
railway upto deploy the application
Note: This worked once and never worked again, and since it became optional we decided to not spend more time on it.
All members have contributed on this phase of the project, the following table shows the contributions of each member:
| Member | Contributions |
|---|---|
| Santiago Arias | API security - Product Rest controller - API Login and signup - API User images - All the Docker stuff - Springdoc |
| Andreas Wolf | Repository to service switch - Cart and wishlist rest controllers - API checkout - Filters - Review rest controller |
| Ignacio Canículo | API support chat (messages) - Message service optimization - Postman collection |
| Inés Alonso | API product images - API review images - Filters |
| Ángel Covarrubias | Review rest controller - Filters - Postman collection |
Santiago Arias
Andreas Wolf
Ignacio Canículo
Inés Alonso
Ángel Covarrubias
Santiago Arias
Andreas Wolf
Ignacio Canículo
Ángel Covarrubias
Prerequisites
Install Node.js and npm (npm v9.5.0+)
Install Angular CLI (Angular CLI 15+)
npm install -g @angular/cli
Note we are taking into account you have all the previous requirements (even from older phases) installed and properly configured.
Steps to follow:
-
Clone the repository:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git -
Go to the folder where the Angular project is located:
cd webapp11/frontend/3techmarketThe file in
src/environments/environment.tsis configured to take the URL of the backend server if this is the same as the IP where the page is being deployed, if your API is located on another server, you need to change this, the development environment is configured to use the following URL:export const environment = { production: false, apiUrl: 'https://localhost:8443/api', apiPrefix: '' };
-
Install the dependencies:
npm install -
Run the project:
ng serveYou have to start the backend server before, otherwise the application will not work properly. Refer to Phase 2 for more information on how to do this. -
Open your browser and go to
http://localhost:4200/. You should see the application running.
Note you can use the create_image.sh script located under webapp11/docker to create the image, this will build the SPA and copy the files to the backend server, ultimately creating a docker image with the backend and the frontend already built.
If instead you want to build the SPA manually, follow the next steps:
- Go to the folder where the Angular project is located:
cd webapp11/frontend/3techmarket - Build the project:
ng build --configuration production --base-href /new/ - The build files will be located in the
distfolder. - Copy the contents of the
distfolder (3techmarket) to thebackend/app/src/main/resources/static/newfolder.
Prerequisites
Note: You need to install Docker, on our machine we installed it using Docker's official documentation (Docker installation steps for Ubuntu), but you can also install it using your distribution's package manager.
Steps to follow:
- ssh into the server:
ssh -i appWeb-11 [email protected] - Clone the repository:
git clone https://github.com/CodeURJC-DAW-2022-23/webapp11.git - Go to the docker folder:
cd webapp11/docker - Run the docker-compose file:
docker-compose up -d - Open your browser and go to
https://10.100.139.166:8443/. You should see the application running. - If you want to stop the application, run:
docker-compose down
The SPA is accessible through the following URL: https://10.100.139.166:8443/new
- ADMIN: [email protected] / 12345678
- USER: [email protected] / 12345678
- AGENT: [email protected] / 12345678
All members have contributed on this phase of the project, the following table shows the contributions of each member:
| Member | Contributions |
|---|---|
| Santiago Arias | Authentication - Profile - Docker script - Product search - Messages - Recent orders - Cart - Environments - Deployment |
| Andreas Wolf | Admin dashboard - Wishlist - Review history - Edit product - Add product - Remove product - Product reviews |
| Ignacio Canículo | Signup - Password recovery - Price history - Environments - Diagrams |
| Inés Alonso | Product view |
| Ángel Covarrubias | Featured products - Add review |