Quizmaster

Quizmaster is a lightweight, self‑hosted web application that turns any server into an interactive quiz platform. Built with a Java 11 runtime, it serves both the master console and player interfaces over HTTP on port 9000. The core logic is driven by a YAML‑based configuration file (conf/quiz/quiz-config.yml) that defines questions, answer types, media assets, scoring rules and optional master authentication. Because the entire quiz state lives in memory during a session, the application is stateless with respect to external services, making it trivially deployable in containers or as a native JAR.

• Language & Runtime: Java 11 (JDK 11) with a lightweight servlet container bundled in the bin/server script.
• Frameworks: The project uses Spring Boot‑like embedded server mechanics (via the jetty or tomcat libraries) to expose REST endpoints and serve static assets.
• Data Layer: No external database is required; all quiz data is parsed from the YAML file at startup. Player scores and current question state are kept in a simple in‑memory data structure, which is reset when the server restarts.
• Front‑end: The UI is a single‑page application written in vanilla JavaScript, CSS and HTML. It consumes the server’s JSON API for real‑time updates (question changes, timer ticks, scoring). The master and player views are differentiated by a query parameter (?role=master) or via the padlock authentication flow.

• Dynamic Question Types: Supports multiple choice, true/false, open‑ended, and media‑rich questions (images, audio, video).
• Scoring API: Exposes endpoints for the master console to record scores and override answers, with optional per‑question weighting.
• Timer & Media Controls: The master API can pause, reset or adjust the timer by 30‑second increments and replay media files.
• Authentication: Optional masterSecret in the config allows a simple token‑based lock to prevent unauthorized master access.
• Extensibility Hooks: The YAML schema can be extended by adding custom fields; the Java code parses unknown keys into a generic map, enabling developers to inject custom logic or plugins.

• Containerization: Official Docker images are provided (docker-compose-prebuilt.yml and docker-compose-build-locally.yml). The application runs as a single container, exposing port 9000.
• Scalability: Because state is in‑memory, scaling horizontally requires sticky sessions or a shared state store. For most use cases (classroom, small events), a single instance suffices.
• Resource Footprint: Minimal RAM (≈200 MB) and CPU usage; suitable for Raspberry Pi or cloud VMs.
• Self‑Hosting Requirements: Only Java 11 and a port open to players. No external services are mandatory, simplifying CI/CD pipelines.

• Plugin System: While no formal plugin API exists, the YAML configuration can reference external URLs for media or embed custom JavaScript in the front‑end.
• Webhooks: Not built‑in, but developers can wrap the server in a reverse proxy that forwards score updates to external services (e.g., Slack, Discord).
• Custom UI: The front‑end is modular; developers can fork the repo, replace the HTML/CSS or add new components without touching the Java backend.
• API Documentation: Basic REST routes are self‑documented via comments; the project includes a /docs endpoint that lists available endpoints and payloads.

• Configuration: The single YAML file is human‑readable and version‑controlled. Changing a quiz requires only editing this file and restarting the container.
• Documentation: The README covers installation, configuration, shortcuts, and deployment patterns. While concise, it provides enough detail for a developer to get up and running in minutes.
• Community & Support: The repository is active on GitHub with CI workflows; issues and pull requests are handled promptly. Licensing is permissive (MIT), allowing commercial use without constraints.

1. Educational Settings – Teachers can host live quizzes during lectures, pulling questions from a shared YAML file.
2. Event & Conference Gamification – Organizers can run audience participation quizzes with real‑time scoring displayed on a large screen.
3. Remote Team Building – Developers can integrate the quiz into CI pipelines, triggering a new quiz after each merge or deployment.
4. Prototype UI/UX Testing – Since the front‑end is decoupled, designers can experiment with new layouts while keeping the backend intact.

• Zero‑Dependency Runtime: No database or external services mean fewer attack vectors and simpler compliance.
• Fast Deployment: Docker images or a single JAR make it trivial to spin up an instance in minutes.
• Extensible Configuration: YAML allows adding new question types or media without code changes.
• Performance & Flexibility: In‑memory state delivers sub‑second updates, while the lightweight stack keeps memory usage low.
• Open Source & MIT Licensed: Developers can modify, redistribute or embed Quizmaster in proprietary products without licensing headaches.

Overall, Quizmaster offers a developer‑friendly