Skip to content

Commit

Permalink
Refactor: Improve README with clarity, structure, and technology details
Browse files Browse the repository at this point in the history 
This update improves the OSC Jukebox React App README by enhancing clarity, organization, and completeness. The document now features more structured sections, including a detailed "Technology Used" segment highlighting React, Vite, Tailwind CSS, Docker, MongoDB, Kafka, and NGINX. These additions provide better context for both new contributors and users exploring the project.

Additionally, the README now includes more intuitive quick-start instructions, clearer explanations of environments and routes. This creates a smooth onboarding experience and empowers beginner contributors to engage more effectively with the project.
  • Loading branch information
@SobaSkee
SobaSkee authored Feb 21, 2025
1 parent 682e99e commit f511e1b
Showing 1 changed file with 54 additions and 110 deletions.
164 changes: 54 additions & 110 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,36 @@
# OSC Jukebox React App
# OSC Jukebox React App 🎵
[![Code Linting](https://github.com/ufosc/Jukebox-Frontend/actions/workflows/code-linting.yml/badge.svg)](https://github.com/ufosc/Jukebox-Frontend/actions/workflows/code-linting.yml)
[![Unit Tests](https://github.com/ufosc/Jukebox-Frontend/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/ufosc/Jukebox-Frontend/actions/workflows/unit-tests.yml)

<!--
[![cov](https://<you>.github.io/<repo>/badges/coverage.svg)](https://github.com/ufosc/Jukebox-Frontend/actions)
-->
## 🚀 Overview

## Overview
Welcome! This project is a microservice attached to the Jukebox Server application and is a fully independent app that can run on its own. 🎶 That means you don't need the server app to explore and contribute here!

Welcome! This project is a microservice attached to the Jukebox Server application, and is a fully independent application that can be run on it's own. What does that mean? It means you don't need to run the server app in order to run this project, and you don't need any experience with the backend to be successful with this project.
Jukebox-Frontend is the graphical interface for the Jukebox project, a dynamic music queuing system designed to allow users to interact with and manage a shared playlist. Built with React ⚛️, it facilitates real-time music selection, queue management, and playback control. 🎸 The project aims to create an intuitive experience where users can seamlessly add, remove, and vote on tracks to influence the queue order. 📊

Jukebox-Frontend is the graphical interface for the Jukebox project, a dynamic music queuing system designed to allow users to interact with and manage a shared playlist. Built with React, it facilitates real-time music selection, queue management, and playback control. The project aims to create an intuitive experience where users can seamlessly add, remove, and vote on tracks to influence the queue order. The interface is optimized for use on various devices, ensuring a smooth experience for all participants. This project is ideal for social gatherings, public spaces, and collaborative listening.

## Quick Start
## ⚡ Quick Start

Inside your terminal or Git Bash:

```sh
# Clone the repo
git clone https://github.com/ufosc/Jukebox-Frontend.git

# Navigate to the project directory
cd Jukebox-Frontend

# Install dependencies
npm install

# Start the app
npm run dev
```

The application can be found at <http://localhost:3000>. When prompted to log in, you can enter anything into the email and password fields.

_NOTE: If running in network mode using `npm run network`, you must first register a user with the api, then login with those credentials. Docs for that coming soon..._
The application can be found at the address displayed in your terminal (most cases it will be http://localhost:3000). When prompted to log in, you can enter anything into the email and password fields.

### Routes
*NOTE: If running in network mode using npm run network, you must first register a user with the api, then login with those credentials. Docs for that coming soon...*

Currently, our url structure looks like this:
## 🌐 Routes

| Path | Description |
| ---------------------------------- | ------------------------------------------------------ |
Expand All @@ -39,127 +40,70 @@ Currently, our url structure looks like this:
| `http://localhost:3000/boards/:id` | Individual boards, values are currently set to 1, 2, 3 |
| `http://localhost:3000/members/` | Members domain |

### Useful Info
## 🛠️ Useful Info

- How to contribute, conventions to follow: [CONTRIBUTING.md](CONTRIBUTING.md)
- Recommended setup: [Wiki/Recommended-Setup](https://github.com/ufosc/Jukebox-Frontend/wiki/Recommended-Setup)

### Environments
## 📋 Prerequisites for Running the Project

- `dev`: Exclusively use mock data, does not need any other servers running
- `network`: Run with production configuration, but allow debug messages (used for integrating with backend)
- `test`: Libs that connect to external services will be mocked
- `production`: No mock data, no debug messages, all errors should be caught, connection to network should be secured
### Node.js

## Prerequisites for Running the Project
Before diving into the OSC Jukebox React App, ensure you have Node.js installed on your system. 🌟 Node.js is a JavaScript runtime that allows you to run JavaScript code outside of a web browser and acts as a package manager for JavaScript. To install it, follow these steps:

### NPM

Before diving into the OSC Jukebox React App, ensure you have npm installed on your system. It's a package manager for JavaScript, primarily used for managing and sharing packages (libraries and tools) of JavaScript code. NPM is widely used in the Node.js ecosystem, but it can also manage front-end dependencies in web development. To install it, follow these steps:

1. Visit the [installer page](https://nodejs.org/en/download)
2. Choose the installer version for your operating system. For example, if you are on Windows, use the `.msi` installer
1. Visit the [Node.js installer page](https://nodejs.org/en/download)
2. Choose the installer version for your operating system.

### Git

If you don't already have Git installed, make sure to so. Git is an open-source version control software supporting online repositories like GitHub, BitBucket, GitLab, and others. Follow these setps for Git installation:
If you don't already have Git installed, make sure to do so. Git is an open-source version control system supporting online repositories like GitHub, BitBucket, GitLab, and others. 📦 Follow these steps for Git installation:

1. Visit the Git [download page](https://git-scm.com/downloads).
2. Choose the "standalone installer" for your operating system.

If you are on windows, we recommend you use the GitBash CLI that comes with the install. Otherwise, if you are on a Unix based system (Linux, MacOS), then use the normal terminal.

## Start-Guide

Now that you have the required tools, you're ready to set up and run the OSC Jukebox React App. To do so, follow these steps:

### Running the Project

1. Get the Code: The easiest way to get the code and interact with it is by forking the directory into your own GitHub account. You can do this by going to the main repo page and clicking the button that
says `Fork` in the top right side of the page. This will create a copy of the repo on your account. In your forked repo, click the green `Code` button and copy the git url. This will be used to clone the project.

2. Clone the project into your local system:

```sh
git clone <git url>
```

3. Acccess the newly created directory and run `npm instal` to install the project's dependencies

```sh
cd Jukebox-Frontend
npm install
```

4. Run `npm run dev` to launch the App on `http://localhost:3000/`.
2. Click the link for your operating system under downloads.
3. Follow directions on this page to install Git for your operating system. For example, on Windows, you just need to download the "standalone installer," but directions differ for other operating systems.

```sh
npm run dev
```
## 🎨 Contribution

When prompted with a login page, just enter any text into the fields and submit it.

Now that you have the project running, let's explore how you can contribute and make a meaningful impact

### Running with Network Mode

If you want to run the project and test it out with the server, use this command:
Here's how you can get involved in contributing to our project:

1. Create a new branch for your feature or fix ✨
```sh
docker-compose -f docker-compose.network.yml build
docker-compose -f docker-compose.network.yml up
git checkout -b feature/your-feature-name
```

This will run the following resources:

- React app in "network" mode
- API Server
- Websocket
- Kafka node
- Kafka Zookeeper
- MongoDB
- NGINX

## Contribution

Here's how you can get involved in contributing to our project:

Aftering forking the repo and cloning your fork to your local system,

1. Create a new branch for your feature or fix
```sh
git checkout -b feature/your-feature-name
```

2. Make your changes and commit them with clear, concise messages
```sh
git commit -m "Add: feature description"
```
2. Make your changes and commit them with clear, concise messages 📝
```sh
git commit -m "Add: feature description"
```

3. Push your branch to your fork
```sh
git push origin feature/your-feature-name
```
3. Push your branch to your fork 🚀
```sh
git push origin feature/your-feature-name
```

4. Create a pull request (PR) by navigating to the original repository and clicking "New Pull Request"
4. Create a pull request (PR) by navigating to the original repository and clicking "New Pull Request" 📤

5. Describe your changes and link to any relevant issues
## 🖥️ Technology Used

## Technology Used
This project leverages cutting-edge web technologies to provide an efficient and responsive user experience:

This project uses **React** and **JavaScript**, making it great for beginners and advanced React developeres simultaneously. React is one of the most used frontend frameworks out there, with alternatives including _Angular_ and _Vue.js_.
- **React:** The core framework used for building the user interface.
- **JavaScript:** The primary programming language for frontend logic.
- **Vite:** Fast build tool and development server.
- **Tailwind CSS:** For streamlined and modern styling.
- **Docker:** Used for network mode deployment and service management.
- **MongoDB:** Database for user and music queue management.
- **Kafka:** Real-time message streaming for events.
- **NGINX:** Reverse proxy for efficient resource handling.

If you want to learn more about React, here are some great starting points:
If you're new to React, here are some great learning resources:

- [React Website](https://react.dev/learn)
- [Mozilla](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started)
- [Medium Article](https://medium.com/swlh/getting-started-with-react-the-fundamentals-61b0266994af)
- [W3 Schools](https://www.w3schools.com/react/react_intro.asp)
- [React Docs](https://react.dev/learn)
- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started)
- [FreeCodeCamp](https://www.freecodecamp.org/news/get-started-with-react-for-beginners/)
- [Online course offered by Udemy](https://www.udemy.com/share/101Wby3@HeSBtGZeq8SlDCjmZiEgFaax3-uYedK2rNgL51o16a0BumHt7txG87pyVbN8ijt5/)
- [Online course offered by Coursera](https://www.coursera.org/learn/react-basics)
- [Online course offered by creator of the Syntax podcast](https://reactforbeginners.com/)
- [W3 Schools](https://www.w3schools.com/react/react_intro.asp)
- [React for Beginners by Wes Bos](https://reactforbeginners.com/)
- [Coursera React Course](https://www.coursera.org/learn/react-basics)

If you want to master React, I recommend you take one of the online courses. They may cost some money, but usually you can get discounts on some of them. However, you don't need to take any of these to become a professional React developer.
Whether you're a beginner or an experienced developer, these tools and resources will help you navigate the project seamlessly. 🚀

One of the resources on that list included a course by Wes Bos - one of the creators of a podcast about web development called Syntax. Listening to professional developers talking about their work and recommendations is also beneficial in learning any programming language, framework, or technique.

0 comments on commit f511e1b

Please sign in to comment.