Our Shelves

A reading tracker web application that allows users to search for books using the Open Library API, save them to their personal digital shelf, and manage their book collection.

Team Members

Sprint 1/2:

Alston
Danny

Sprint 3:

Kim
Maddie

Sprint 4:

Tav
Tia

Project Description

Our Shelves lets users:

Search for books by title using the Open Library API.
Add books to their personal shelf stored in a MySQL database.
View their saved books.
Delete books from their library.
Interact with a React frontend and Express backend, connected via REST API.

Future Feature Goals

Add personal notes to books.
Track bookmarks / reading progress.
Organize books into multiple shelves.
Share shelves and notes with friends.
Support light/dark theme customization.

Tech Stack

Layer	Technology
Frontend	React (Vite), React Router
Backend	Node.js, Express.js
Database	MySQL (`mysql2/promise`)
External API	Open Library API
Packaging	Docker
Deployment	Ubuntu Server

Prerequisites

Make sure the following are installed:

Environment Variables

Inside project root `env`

# db & api
MYSQL_USER=username
MYSQL_PASSWORD=superSecurePassword
MYSQL_DATABASE=my_favorite_db

# api
DB_PORT=3306
PORT=3000
HOST=localhost

# frontend
VITE_API_URL=http://${HOST}:${PORT}

For production, replace localhost with your server IP or domain name.

Local Development Setup

1. Clone the Repository

git clone https://github.com/your-username/our-shelves.git
cd our-shelves

2. Install Dependencies

cd backend
npm install

cd ../frontend
npm install

3. Set Up `.env` File

Create .env inside root directory.
Copy and paste the environment variable structure shown above.

Testing Strategy

This project includes unit tests for both the frontend and backend, integration tests, as well as end-to-end (E2E) tests.

Backend - Unit Tests (Jest)

Purpose: Tests individual backend controllers in isolation. All database calls (db.js) and fetch requests are mocked, so no database or network connection is required.

How to Run:

cd backend
npm test

This command runs all files ending in .test.js found in the backend/tests folder.

Frontend - Unit Tests (Vitest & React Testing Library)

Purpose: Tests individual React components in a simulated browser environment. All fetch API calls are mocked in the setup file (frontend/src/setupTests.js).

How to Run:

cd frontend
npm test

This command will start Vitest in "watch mode," automatically re-running tests as you save changes.

Coverage Reports

To generate a coverage report, cd into the respective directory (backend/frontend) and run the following command

npm test -- --coverage

Backend - Integration Tests (Jest & Testcontainers)

Purpose: Tests the live application routes and controllers against a real, temporary database. This ensures all database queries, joins, and logic work as expected.

Requirements: Docker must be installed and running on your system

How to Run:

cd backend
npm run test:integration

End-to-End (E2E) Tests (Cypress)

Purpose: Simulates a real user journey in a real browser. It tests the complete application flow, from searching for a book to adding it to the library and deleting it.

How to Run (2 Steps):

Start the frontend dev server:

cd frontend
npm run dev

Open the Cypress runner:

Important - Make sure to do this in a new terminal window

cd frontend
npx cypress open

This will open the Cypress app. From there, you can choose a browser and run the app.cy.js test suite.

Generating Videos & Screenshots (Cypress Headless Mode)

Purpose: Runs the tests in the terminal without opening a popup window. This mode is required to generate video recordings and error screenshots.

How to Run:

Ensure the frontend dev server is running (if not already):

cd frontend
npm run dev

Open a new terminal:

cd frontend
npx cypress run

Output:

Videos are saved to: frontend/cypress/videos
Screenshots (on failure) are saved to: frontend/cypress/screenshots

Running the Application (Local)

The backend, frontend, and MySQL server can all be built and ran with one command:

docker compose up -d

Deployment Instructions (Ubuntu + Docker)

1. Update VM and Install Dependencies

Updating:

apt update
yes | sudo DEBIAN_FRONTEND=noninteractive apt-get -yqq upgrade

Install Git

apt install git

Install Docker Engine With apt Repository Setup apt repo:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Install docker package:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Confirm docker is installed and running:

sudo systemctl status docker

Install docker compose

sudo apt-get update
sudo apt-get install docker-compose-plugin

2. Clone Repository

git clone https://github.com/your-username/our-shelves.git
cd our-shelves

3. Add .env to repository

nano .env

Inside nano text editor:

# db & api
MYSQL_USER=username
MYSQL_PASSWORD=superSecurePassword
MYSQL_DATABASE=my_favorite_db

# api
DB_PORT=3306
PORT=3000
HOST=<VM IP>

# frontend
VITE_API_URL=http://${HOST}:${PORT}

Ctrl + o to save Ctrl + x to exit

Check if .env exists:

ls -a

4. Build and Deploy Docker Images

The application can be built and deployed with one command now:

docker compose up -d

The frontend will be running on the VMs IP address defined in the env, on PORT 5173. ex: http://0.0.0.0:5173 (replace 0.0.0.0 with VM IP)

API Endpoints

Method	Endpoint	Description
GET	`/books`	Fetch all saved books
POST	`/books`	Add a new book
DELETE	`/books/:id`	Delete a book by ID
GET	`/books/search/:bookName`	Search books via Open Library API

Useful Commands

Updating Deployed App:

git pull
docker compose up -build

Stopping:

docker compose down

Troubleshooting Tips

Ensure .env files are correctly configured
Confirm no leading spaces in env variables
Check firewall settings if deploying to a remote server (allow ports 3000 and 5173).

License

This project is for educational use as part of a student project at Green River College.

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
ecosystem.config.js		ecosystem.config.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Our Shelves

Team Members

Project Description

Future Feature Goals

Tech Stack

Prerequisites

Environment Variables

Inside project root env

Local Development Setup

1. Clone the Repository

2. Install Dependencies

3. Set Up .env File

Testing Strategy

Backend - Unit Tests (Jest)

Frontend - Unit Tests (Vitest & React Testing Library)

Coverage Reports

Backend - Integration Tests (Jest & Testcontainers)

Requirements: Docker must be installed and running on your system

End-to-End (E2E) Tests (Cypress)

Important - Make sure to do this in a new terminal window

Generating Videos & Screenshots (Cypress Headless Mode)

Running the Application (Local)

Deployment Instructions (Ubuntu + Docker)

1. Update VM and Install Dependencies

2. Clone Repository

3. Add .env to repository

4. Build and Deploy Docker Images

API Endpoints

Useful Commands

Troubleshooting Tips

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Inside project root `env`

3. Set Up `.env` File

Packages