README

.github/workflows/sync-to-hf.yaml

@@ -24,9 +24,4 @@ jobs:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           git remote add space https://huggingface.co/spaces/ruslanmv/Real-Time-Quiz-Application || true
-          git push --force https://ruslanmv:${HF_TOKEN}@huggingface.co/spaces/ruslanmv/Real-Time-Quiz-Application main
-
-      # Step to restore original README.md
-      - name: Restore GitHub README.md
-        run: |
-          mv README_GITHUB.md README.md
+          git push --force https://ruslanmv:${HF_TOKEN}@huggingface.co/spaces/ruslanmv/Real-Time-Quiz-Application main

README.md

@@ -1,15 +1,148 @@
----
-title: Real Time Quiz Application
-emoji: 🔥
-colorFrom: green
-colorTo: pink
-sdk: docker
-pinned: false
-short_description: 'About A Python-based real-time quiz application designed to '
----
+# 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.
+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)
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference