diff --git a/submissions/quizhub-ai_bumble-bee.md b/submissions/quizhub-ai_bumble-bee.md new file mode 100644 index 0000000..09251c6 --- /dev/null +++ b/submissions/quizhub-ai_bumble-bee.md @@ -0,0 +1,152 @@ +# QuizHub AI + +--- + +## Attendee/Team Details + +**Team Name:** Bumble Bee + +**Member 1** +- **Name:** Veera Shankar Udu +- **GitHub Username:** veerashankarudu +- **LinkedIn Profile:** + +**Member 2** +- **Name:** Teja Krishna B +- **GitHub Username:** +- **LinkedIn Profile:** + +**GitHub Project Repository:** https://github.com/veerashankarudu/React_Hyderbad_Vercel + +--- + +## Problem Statement Selected + + + +--- + +## 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:** + +**Demo Video 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.