Skip to content

Submission: QuizHub AI - Bumble Bee #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Tejakrishna-b wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Submission: QuizHub AI - Bumble Bee #37

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 152 additions & 0 deletions submissions/quizhub-ai_bumble-bee.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# QuizHub AI

---

## Attendee/Team Details

**Team Name:** Bumble Bee

**Member 1**
- **Name:** Veera Shankar Udu
- **GitHub Username:** veerashankarudu
- **LinkedIn Profile:** <add Veera's LinkedIn URL>

**Member 2**
- **Name:** Teja Krishna B
- **GitHub Username:** <add Teja's GitHub username>
- **LinkedIn Profile:** <add Teja's LinkedIn URL>

**GitHub Project Repository:** https://github.com/veerashankarudu/React_Hyderbad_Vercel

---

## Problem Statement Selected

<Paste the exact title from PROBLEM_STATEMENTS.md in the hackathon repo here, e.g. "Problem statement 1" or "Problem statement 2">

---

## Project Description

**QuizHub AI** is an enterprise-grade MCQ (Multiple Choice Question) lifecycle platform built for Valkey's internal learning ecosystem. It lets Subject Matter Experts (SMEs) create, review, and manage MCQs through an AI-assisted, governed workflow with role-based access control, bulk operations, proctored assessments, live Kahoot-style quizzes, and 7-language support.

Every MCQ moves through a controlled lifecycle:
**DRAFT → READY_FOR_REVIEW → UNDER_REVIEW → APPROVED / REJECTED**

This guarantees quality, consistency, and a full audit trail across the organisation.

- **Who is it for?** Enterprise learning teams, SMEs, reviewers, and admins running internal training programs.
- **What problem does it solve?** Manual MCQ creation is slow, inconsistent, and ungoverned. QuizHub AI standardises the lifecycle, removes duplicates with AI, accelerates authoring with AI generation, and makes quality measurable.
- **How does it help the user?** Faster authoring (AI generates the question, distractors, and explanations), built-in duplicate detection, controlled reviews with SLA tracking, proctored quizzes, and real-time live battles for fun engagement.

---

## Approach

- **State-machine modelling:** The MCQ lifecycle is an explicit state machine enforced server-side; invalid transitions are blocked at the service layer.
- **Strict RBAC:** Two roles — `ADMIN` and `SME` — enforced both at React routes (`PrivateRoute`) and at Spring controllers (`@PreAuthorize`).
- **AI layer:** Spring AI + GPT-4o-mini powers generation, distractor creation, quality scoring, semantic duplicate detection, and screenshot-to-MCQ extraction. AI failures degrade gracefully — the app remains fully usable.
- **Live Quiz Battle:** A Kahoot-style real-time multiplayer mode over WebSocket (STOMP/SockJS) with 6-digit PIN join, live leaderboard, host controls (pause/resume/extend/kick), team mode, and reconnect support.
- **Resilient infra:** Redis (primary cache) with automatic Caffeine in-process fallback, Lingva → MyMemory translation fallback, profile-aware structured JSON logs, request correlation IDs via MDC.
- **Production observability:** One-command Prometheus + Grafana via Docker Compose, auto-provisioned dashboard, 25 business metrics, JVM + HTTP metrics with SLO histograms.
- **AI agent integration:** A Spring AI MCP server (port 8085) exposes 8 tools so Claude Desktop or GitHub Copilot can query and operate on the platform.

---

## Tech Stack and Tools Used

**Frontend:** React 19, React Router 7, Axios, i18next (7 languages incl. Urdu RTL), React Toastify, html2canvas

**Backend:** Java 17, Spring Boot 3.2.5, Spring Security 6, Spring Data JPA, Spring AI 1.0, Spring Cache, Spring WebSocket (STOMP/SockJS), JWT (JJWT), Apache POI, OpenCSV, Springdoc OpenAPI

**Database:** MySQL 8.x (with Hibernate L1 cache)

**Cache:** Redis 7 (primary) with automatic Caffeine fallback if Redis is unavailable

**AI Tools/API:** OpenAI GPT-4o-mini (via Spring AI), Lingva + MyMemory APIs (translation), OpenAI Vision API (screenshot-to-MCQ)

**Cloud/Deployment:** Docker Compose (local + observability stack)

**Observability:** Prometheus, Grafana (auto-provisioned dashboard), Micrometer, Logstash Logback Encoder (JSON logs), optional Datadog OTLP

**MCP Server:** Spring Boot 3.4.1 + Spring AI MCP 1.0 (8 tools registered, SSE on `:8085`)

**Other Tools:** GitHub Copilot, Maven, npm, Postman, Swagger UI, JUnit 5, Mockito, Jest, React Testing Library

---

## Key Features

1. **AI-assisted MCQ authoring** — generate full MCQs from a topic, auto-create distractors, validate answers, score quality 0–100, and detect semantic duplicates (≥10% flag, ≥30% block).
2. **Live Quiz Battle (Kahoot-style)** — 6-digit PIN join, real-time WebSocket leaderboard, host controls, team mode, certificate generation, session replay, reconnect support.
3. **Proctored assessments** — tab-switch + fullscreen-exit detection, screenshot capture on first violation (`html2canvas`), 3-strike auto-submit, exam-lock guard against multi-tab.
4. **Role-based admin & SME workflows** — assign reviewers, audit log, master data, reviewer metrics with admin-configurable SLA breach thresholds.
5. **7-language i18n** — English, Hindi, French, Kannada, Telugu, German, Urdu (full RTL layout); dynamic content translation via Lingva → MyMemory fallback.
6. **Production-grade observability** — Prometheus + Grafana auto-provisioned, 25 `quizhub.*` business metrics, structured JSON logs, X-Request-Id correlation tracing.
7. **AI Studio** — Code → MCQ generator (10 languages), AI rewrite of weak questions, personalised learning paths, Smart Interview Kit (resume + optional JD → tailored questions).
8. **MCP server for AI agents** — 8 tools (`searchQuestions`, `checkDuplicate`, `createMcq`, `getStats`, etc.) exposed over SSE for Claude Desktop / GitHub Copilot integration.

---

## What is Working?

- All 450 features end-to-end: auth, MCQ lifecycle, bulk upload, AI generation, live quiz battle, proctored quizzes, leaderboard, analytics, RBAC, i18n, observability.
- **2,029 automated tests passing** — 1,072 backend (92.5% JaCoCo coverage) + 957 frontend (80.37% statement coverage).
- Redis ↔ Caffeine auto-fallback, Prometheus/Grafana dashboard, JSON logs, MCP server.
- One-command startup: `bash start.sh` brings up MySQL DB seeding, observability stack, backend, and frontend.

## What is Still in Progress?

- Cloud deployment (currently local-first via Docker Compose).
- Native mobile apps (the web is mobile-responsive across 11 pages, but native iOS/Android is not started).
- Expanded language coverage beyond the current 7.
- Additional AI providers (currently OpenAI only — plan to add Anthropic and local LLMs via Ollama).

---

## Screenshots or Demo

**Deployed Link:** <add if deployed, else: Local only — see setup instructions in the repo README>

**Demo Video Link:** <add YouTube / Loom link>

**Screenshots:** See the `demo-shots/` folder in the project repository: https://github.com/veerashankarudu/React_Hyderbad_Vercel/tree/main/demo-shots

---

## Challenges Faced

- Designing a state machine strict enough to prevent invalid transitions but flexible enough for legitimate admin overrides.
- Real-time WebSocket reconnection in the Live Quiz Battle — handling host disconnect, participant rejoin, and consistent score state across reconnects.
- Tuning semantic duplicate detection thresholds (≥10% flag / ≥30% block) to balance false positives vs missed duplicates.
- Building graceful degradation paths for every external dependency: Redis, OpenAI, Lingva, MyMemory, SMTP — the app must remain fully usable when any of them are down.
- Pre-declaring Prometheus metrics at startup so Grafana panels render `0` instead of "No data" on first boot.

---

## Learnings

- Spring AI 1.0 patterns for production AI integration with fallbacks and bounded latency.
- Auto-provisioning Grafana datasources + dashboards via Docker Compose for zero-touch observability.
- Designing resilience as a first-class concern — cache fallback, translation fallback, AI fallback — all silent and automatic.
- Using MDC + a request correlation filter so every log line is traceable to a single request, user, and role.
- Exposing a Spring AI MCP server makes the platform programmable by external AI agents with zero glue code.

---

## Future Improvements

- Deploy to Azure / GCP with managed Redis + MySQL + Kubernetes.
- Add OAuth2/SSO (Google, Microsoft Entra).
- Add more AI providers (Anthropic, local LLMs via Ollama) with a strategy pattern.
- Native mobile apps (iOS + Android).
- Multi-tenant support so multiple organisations can run isolated instances.
- Real-time collaborative MCQ editing.

---

## Final Note

QuizHub AI was built to be **production-grade, not just a hackathon demo** — 450 features, 2,029 automated tests, full Prometheus + Grafana observability stack, an MCP server for AI agent integration, and a documented graceful-degradation strategy for every external dependency.

Built with ❤️ by **Team Bumble Bee** — Veera Shankar Udu & Teja Krishna B — for **Build Beyond Limits 2.0**, powered by Valkey and hosted by React Hyderabad.