README_GITHUB.md

# Real-Time Quiz Application

A Python-based real-time quiz application designed to mimic the functionality of **Mentimeter**, allowing a host to control the quiz and participants (clients) to join, answer questions, and receive immediate feedback. The application is built using **Flask** and **Socket.IO** for seamless web-based interaction, and it offers a clean, responsive front-end using **HTML**, **CSS**, and **Bootstrap**.

## Features

- **Real-Time Communication**: Uses **Socket.IO** for instant updates between the host and clients.
- **Participant Management**: Tracks connected clients, showing their usernames and responses in real time.
- **Interactive Host Control**: The host can change questions, see live results, and control the flow of the quiz.
- **Simple and Responsive Front-End**: Clean design using Bootstrap for a pleasant user experience across devices.
- **Scalable Design**: Easily expandable to support more questions, features, and visualizations.

## Project Structure

```bash
Real-Time-Quiz-Application/
│
│
├── app.py                # Main Flask application
├── backend.py            # Backend logic for loading and managing exams
├── templates/
│   ├── index.html        # Main index page with client and host buttons
│   ├── client.html       # Client interface
│   └── host.html         # Host interface
├── static/
│   ├── style.css         # Custom styles to mimic the OnVUE exam appearance
│   └── script.js         # JavaScript for real-time interactions
├── questions/            # Folder containing exam JSON files
│   ├── exam1.json        # Example JSON file for exam 1
│   ├── exam2.json        # Example JSON file for exam 2
├── requirements.txt      # Python dependencies
└── README.md             # Project documentation
```

## Requirements

Ensure you have Python 3.6+ installed. The required dependencies are listed in `requirements.txt`:

- **Flask**: The web framework used for developing the application.
- **Flask-SocketIO**: Enables real-time WebSocket communication between the server and clients.

Install dependencies with:

```bash
pip install -r requirements.txt
```

## How to Run the Application

1. **Clone the repository**:
   ```bash
   git clone https://github.com/ruslanmv/Real-Time-Quiz-Application.git
   cd Real-Time-Quiz-Application
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the application**:
   ```bash
   python app.py
   ```
![](assets/2024-10-21-17-07-42.png)
4. **Access the application**:
   - **Host interface**: [http://127.0.0.1:5000/host](http://127.0.0.1:5000/host)
![](assets/2024-10-21-17-08-13.png)
   - **Client interface**: [http://127.0.0.1:5000/client](http://127.0.0.1:5000/client)
![](assets/2024-10-21-17-09-15.png)
## Application Overview
![](assets/2024-10-21-17-18-28.png)
### Host Interface

The host controls the flow of the quiz:
- **View Questions**: See the current question and available options.
- **Next Question**: Advance to the next question.
- **Live Results**: View participant responses and statistics in real time.

### Client Interface

Participants join the quiz and interact with the questions:
- **Join the Quiz**: Enter a temporary username to participate.
- **Receive Questions**: Answer questions as they appear, with four possible options.
- **Live Feedback**: See the result of each question based on group responses.

## Demonstration

For demonstration purposes, this version includes only **two questions**. The questions are stored in `app.py` as follows:

```python
questions = [
    {"question": "What is the capital of France?", "options": ["Paris", "London", "Berlin", "Rome"]},
    {"question": "What is the largest planet?", "options": ["Earth", "Mars", "Jupiter", "Saturn"]}
]
```

### Adding More Questions

To add more questions, simply update the `questions` list in `app.py`. Ensure each question follows the structure:
```python
{"question": "Your question here?", "options": ["Option1", "Option2", "Option3", "Option4"]}
```

## Scaling the Application

This application is built to be easily scalable:
- **Add More Features**: Integrate additional features such as timed questions, answer explanations, or leaderboard tracking.
- **Expand Real-Time Visuals**: Enhance client-side interactivity with more detailed results or progress tracking.
- **Deploy the App**: Use services like **Heroku**, **AWS**, or **Docker** to deploy the application for larger audiences.

## Dependencies

Ensure you have the following dependencies installed, as listed in `requirements.txt`:

```
Flask
Flask-SocketIO
```

### Installing Dependencies

```bash
pip install -r requirements.txt
```

## Troubleshooting

- **No participants showing up**: Ensure all participants join the `/client` interface and submit their usernames correctly.
- **WebSocket issues**: Make sure your firewall or browser settings are not blocking WebSocket connections.
- **Server not starting**: Check that Flask and Flask-SocketIO are installed correctly.

## Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue to improve the functionality, design, or documentation of this application.

## License

This project is open-source and licensed under the MIT License.

## Contact

For any inquiries or suggestions, please reach out to:

- **Name**: Ruslan Magana Vsevolodovna
- **Email**: contact@ruslanmv.com
- **GitHub**: [https://github.com/ruslanmv](https://github.com/ruslanmv)