🧠 QuizBoot

A Modern, Scalable Quiz Management System Built with Spring Boot

🚀 Quick Start • 📖 Documentation • 🛠️ API Reference • 🤝 Contributing

---

✨ Features

🎯 Quiz Management Multi-category quiz creation with flexible question types Real-time quiz sessions with timer functionality Advanced scoring algorithms with instant feedback Quiz publishing workflow with approval system	👥 User Experience Role-based access control (Admin, Instructor, Student) JWT-based authentication with refresh tokens Progress tracking and analytics dashboard Responsive web interface for all devices
🔒 Security & Performance Spring Security 6.x integration BCrypt password hashing Rate limiting and CORS protection Database optimization with proper indexing	🏗️ Modern Architecture Spring Modulith for modular design Clean Architecture principles RESTful API with OpenAPI documentation Production-ready with monitoring support

---

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

• ☕ Java 21 or higher (Download)
• 🐬 MySQL 8.0+ (Download)
• 📦 Maven 3.8+ (included via Maven Wrapper)
• 🔧 Git (Download)

🏃‍♂️ Running Locally

1. Clone the repository

   git clone https://github.com/Omar-Mega-Byte/QuizBoot.git
   cd QuizBoot

2. Set up the database

   CREATE DATABASE quizdb;
   CREATE USER 'quizuser'@'localhost' IDENTIFIED BY 'quizpassword';
   GRANT ALL PRIVILEGES ON quizdb.* TO 'quizuser'@'localhost';
   FLUSH PRIVILEGES;

3. Configure environment variables (optional)

   export MYSQL_HOST=localhost
   export MYSQL_PORT=3306
   export MYSQL_DB=quizdb
   export MYSQL_USER=quizuser
   export MYSQL_PASSWORD=quizpassword
   export SERVER_PORT=8080

4. Run the application

   ./mvnw spring-boot:run

5. Access the application

   • 🌐 Application: http://localhost:8080
   • 📚 API Documentation: http://localhost:8080/swagger-ui.html
   • ❤️ Health Check: http://localhost:8080/actuator/health

---

🐳 Docker Setup

# Build and run with Docker Compose (coming soon)
docker-compose up -d

# Or build manually
docker build -t quizboot .
docker run -p 8080:8080 --env-file .env quizboot

---

🛠️ API Reference

QuizBoot provides a comprehensive RESTful API. Here are some key endpoints:

🔐 Authentication

POST /api/v1/auth/register     # User registration
POST /api/v1/auth/login        # User login
POST /api/v1/auth/refresh      # Token refresh

📝 Quiz Management

GET    /api/v1/quizzes         # List all quizzes
POST   /api/v1/quizzes         # Create new quiz
GET    /api/v1/quizzes/{id}    # Get quiz details
PUT    /api/v1/quizzes/{id}    # Update quiz
DELETE /api/v1/quizzes/{id}    # Delete quiz

🏃‍♂️ Quiz Sessions

POST /api/v1/sessions              # Start new quiz session
PUT  /api/v1/sessions/{id}/answers # Submit answer
POST /api/v1/sessions/{id}/submit  # Submit entire session

📊 Analytics

GET /api/v1/analytics/users/{id}   # User analytics
GET /api/v1/analytics/quizzes/{id} # Quiz analytics
GET /api/v1/reports/user-progress  # Progress reports

📚 Full API Documentation: Available at /swagger-ui.html when running the application

---

🏗️ Architecture

QuizBoot follows a modern modular architecture using Spring Modulith:

📦 com.example.quiz_boot
├── 👤 user/              # User Management Module
├── 📝 quiz/              # Quiz Management Module  
├── 🏃 session/           # Session Management Module
├── 📊 analytics/         # Analytics & Reporting Module
└── 🔧 shared/            # Shared Components & Utilities

Key Technologies

Category	Technology	Purpose
Framework	Spring Boot 3.5.4	Main application framework
Security	Spring Security 6.x	Authentication & authorization
Database	MySQL 8.0+ & Hibernate	Data persistence
Architecture	Spring Modulith	Modular application design
Documentation	OpenAPI/Swagger	API documentation
Monitoring	Spring Actuator	Application monitoring

🔍 Detailed Architecture: See PROJECT_ARCHITECTURE.md for comprehensive technical documentation

---

🔧 Development

Building the Project

# Compile
./mvnw compile

# Run tests
./mvnw test

# Package
./mvnw package

# Skip tests (for faster builds)
./mvnw package -DskipTests

Code Quality

We maintain high code quality standards:

• ✅ 80%+ test coverage requirement
• 🔍 SonarQube integration for code analysis
• 📝 Google Java Style Guide compliance
• 🔒 Mandatory code reviews for all changes

Development Profiles

Profile	Purpose	Database
default	Local development	MySQL
test	Testing	H2 in-memory
staging	Pre-production	MySQL cluster
production	Production	MySQL with replication

---

🌟 Contributing

We welcome contributions! Here's how you can help:

🐛 Reporting Issues

• Use our issue template
• Include detailed steps to reproduce
• Add relevant logs and screenshots

🚀 Submitting Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our coding standards
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📋 Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/QuizBoot.git

# Add upstream remote
git remote add upstream https://github.com/Omar-Mega-Byte/QuizBoot.git

# Create development branch
git checkout -b feature/your-feature-name

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Spring Team for the amazing Spring Boot framework
• Contributors who help make this project better
• Open Source Community for inspiration and support

---

📞 Support

• 📧 Email: omar.tolis2004@gmail.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ by the QuizBoot Team

⭐ Star this repo if you find it useful! ⭐

🔝 Back to Top