Practice smarter, rank higher — A comprehensive desktop quiz application for Mining Engineering students
- Overview
- Key Features
- Screenshots
- Architecture
- Tech Stack
- Installation
- Usage
- Configuration
- Database Schema
- Building & Deployment
- Project Structure
- Troubleshooting
- FAQ
- Roadmap
- Contributing
- License
- Credits
Mining Exam Prep is a feature-rich, offline-first desktop application designed specifically for Mining Engineering students to prepare for exams, track their progress, and compete on leaderboards. Built with PyQt6, it combines quiz functionality with advanced analytics, gamification, and learning tools.
- 🎓 Specialized Content: Questions tailored for Mining Engineering subjects
- 📊 Advanced Analytics: Track performance, identify weak topics, and monitor progress
- 🏆 Gamification: Earn XP, maintain streaks, compete on leaderboards
- 📚 Learning Tools: Concept cards, spaced repetition, mistake tracking
- 👥 Multi-User Support: Role-based access (Student, Faculty, Admin)
- 🔒 Offline-First: Full functionality without internet connectivity
- 💾 Automatic Backups: Database backups every 15 minutes
- Multiple Quiz Modes: Practice, Mock Test, Topic-wise, Custom
- Question Types: MCQ, Numeric Answer, Scenario-based
- Smart Question Selection: Adaptive difficulty, topic-based filtering
- Session Persistence: Resume incomplete quizzes seamlessly
- Bookmarking & Review: Save questions for later review
- Detailed Explanations: Learn from mistakes with comprehensive explanations
- Performance Dashboard: Real-time stats, accuracy trends, topic analysis
- Advanced Charts: Matplotlib-powered visualizations
- Subject-wise Performance: Track progress across different subjects
- Speed Analysis: Questions per minute (QPM) tracking
- Historical Trends: Performance evolution over time
- Export Reports: Excel/PDF report generation
- Concept Cards: Formulas, definitions, shortcuts, common mistakes
- Spaced Repetition: AI-powered revision scheduling (1, 3, 7, 14, 30 days)
- Mistake Book: Track and retry wrong questions
- Topic Study Packs: Comprehensive study material per topic
- Built-in Calculators: Mining-specific calculation tools
- Law References: Quick access to relevant mining regulations
- XP & Leveling: Earn experience points for quizzes
- Streak System: Maintain daily practice streaks
- Daily Goals: Set and track daily question targets
- Badges & Achievements: Unlock rewards for milestones
- Leaderboards: Global, subject-wise, and batch-wise rankings
- Certificate Generation: Auto-generated certificates for achievements
- Role-Based Access: Student, Faculty, Admin
- Guest Mode: Try without registration
- Batch Management: Organize students by class/department
- User Profiles: Avatar colors, profile photos, statistics
- Security: Hashed passwords, security questions, account recovery
- Question Bank Management: Create, edit, approve questions
- Assignment Creation: Assign quizzes to specific batches
- Student Monitoring: Track individual and batch performance
- Bulk Question Import: Excel/JSON import support
- Question Review System: Approve pending questions
- LAN Synchronization: Real-time leaderboard sync across network
- Auto-Updates: Question bank updates via manifest files
- Backup & Recovery: Automated backups with restore functionality
- Crash Recovery: Auto-save drafts, restore UI state
- Notification System: Smart notifications for assignments, achievements
- Dark Theme: Modern, eye-friendly dark UI
- Responsive Design: Optimized for various screen sizes
📸 Screenshots will be added here showcasing:
- Login screen with dark theme
- Main dashboard with analytics
- Quiz interface with question display
- Leaderboard rankings
- Question bank management
- Analytics charts and reports
- Learning tools interface
┌─────────────────────────────────────────────────────┐
│ UI Layer (PyQt6) │
│ ┌──────────┬──────────┬──────────┬──────────────┐ │
│ │Dashboard │Quiz │Learning │Analytics │ │
│ │Widget │Widget │Widget │Widget │ │
│ └──────────┴──────────┴──────────┴──────────────┘ │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Service Layer │
│ ┌──────────┬──────────┬──────────┬──────────────┐ │
│ │Quiz │Learning │Analytics │Leaderboard │ │
│ │Engine │Service │Service │Service │ │
│ ├──────────┼──────────┼──────────┼──────────────┤ │
│ │Question │Notification│Backup │Admin │ │
│ │Manager │Service │Service │Service │ │
│ └──────────┴──────────┴──────────┴──────────────┘ │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Data Layer (SQLite) │
│ ┌──────────────────────────────────────────────┐ │
│ │ 17 Tables: Users, Questions, Results, etc. │ │
│ │ ACID Transactions, Foreign Keys, Indexes │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
| Component | Responsibility |
|---|---|
| UI Layer | PyQt6 widgets for user interaction, theming, responsiveness |
| Service Layer | Business logic, quiz engine, analytics, gamification |
| Data Layer | SQLite database with 17 normalized tables |
| Auth System | User authentication, session management, security |
| Backup System | Automated backups, restore, crash recovery |
| LAN Service | Network broadcasting, leaderboard sync |
| Update System | Question bank updates via JSON manifests |
| Technology | Version | Purpose |
|---|---|---|
| Python | 3.10+ | Core language |
| PyQt6 | 6.7.0+ | Desktop UI framework |
| SQLite | 3.x | Embedded database |
| Matplotlib | 3.8.0+ | Chart visualization |
| Pandas | 2.2.0+ | Data processing & analytics |
| OpenPyXL | 3.1.0+ | Excel export/import |
| PyInstaller | 6.6.0+ | Executable building |
- PyQt6.QtWidgets: UI components (QPushButton, QTableWidget, etc.)
- PyQt6.QtCore: Threading, signals/slots, event handling
- PyQt6.QtGui: Graphics, icons, fonts, colors
- matplotlib.backends.backend_qt5agg: Embedded charts in PyQt6
- hashlib: Password hashing (SHA-256)
- json: Configuration, data serialization
- pathlib: Cross-platform file path handling
- datetime: Timestamps, scheduling, time tracking
- contextlib: Database connection management
- dataclasses: Type-safe entity models
- Python 3.10 or higher
- pip (Python package manager)
- Git (for cloning the repository)
- Operating System: Windows, macOS, or Linux
git clone https://github.com/yourusername/mining-quiz-app.git
cd mining-quiz-app# Windows
python -m venv venv
venv\Scripts\activate
# macOS/Linux
python3 -m venv venv
source venv/bin/activatepip install -r requirements.txtpython --version # Should show 3.10+
pip list # Verify all packages installedpython main.pyDownload the pre-built executable from Releases and run directly (no Python installation required).
- Launch Application: Run
python main.py - Login Screen: You'll see the login interface
- Default Admin Account:
- Username:
admin - Password:
admin@123A - Security Question: "What is your favorite mining subject?"
- Security Answer: "Mining Engineering"
- Username:
- Click "Register" on the login screen
- Fill in your details:
- Username (unique)
- Full name
- Password (must include uppercase, lowercase, number, special char)
- Security question & answer (for password recovery)
- Click "Create Account"
- Login with your new credentials
- Select Quiz Mode from the dashboard:
- Practice Mode: Casual practice with immediate feedback
- Mock Test: Timed exam simulation
- Topic Quiz: Focus on specific topics
- Custom Quiz: Configure difficulty, subjects, question count
- Configure Settings: Questions count, time limit, subjects
- Start Quiz: Click "Start Quiz"
- Answer Questions: Select options, bookmark for review
- Submit: Review summary and submit
- View Results: Detailed analytics, correct answers, explanations
- Navigate to "Learning" tab
- Concept Cards: Browse formulas, definitions, shortcuts
- Mistake Book: Review and retry wrong questions
- Revision Schedule: See upcoming spaced repetition tasks
- Calculators: Use mining-specific calculation tools
- Login as Faculty or Admin
- Question Bank: Create, edit, approve questions
- Assignments: Create assignments for specific batches
- Analytics: View student performance, batch statistics
- Export: Generate Excel reports of student performance
- Login as Admin (username:
admin, password:admin@123A) - User Management: Create, modify, delete users
- Batch Management: Create and manage student batches
- System Logs: View admin actions, audit trail
- Backups: Manual backup creation, restore from backups
- Updates: Push question bank updates via manifests
Edit app/config.py to customize:
# Application Identity
APP_NAME = "Mining Exam Prep"
APP_VERSION = "2.0.0"
APP_TAGLINE = "Practice smarter, rank higher"
# Session & Security
SESSION_TIMEOUT_SEC = 2 * 60 * 60 # 2 hours
REMEMBER_ME_KEY = "remembered_user_id"
# Backup Settings
BACKUP_INTERVAL_SEC = 15 * 60 # 15 minutes
BACKUP_KEEP_COUNT = 12 # Keep last 12 backups
# LAN Sync (for leaderboard)
LAN_BROADCAST_PORT = 45678
LAN_SYNC_INTERVAL_SEC = 15
# Pagination
QUESTION_BANK_PAGE_SIZE = 100Default database path: data/mining_quiz.db
To change:
# In app/config.py
DB_PATH = DATA_DIR / "custom_name.db"The application uses a dark theme defined in app/ui/theme.py:
# Modify colors in DARK_THEME constant
DARK_THEME = """
QWidget {
background-color: #1a1a2e;
color: #eaeaea;
font-family: 'Segoe UI', Arial, sans-serif;
}
...
"""assets/
├── default/ # Default assets (fallbacks)
├── icons/ # Application icons
├── photos/ # User profile photos
└── wallpapers/ # Background images
The application uses SQLite with 17 normalized tables:
| Table | Description | Key Columns |
|---|---|---|
| users | User accounts | id, user_id, name, password_hash, role, xp, streak |
| questions | Question bank | id, subject, topic, question_text, correct_option, explanation |
| quiz_sessions | Active quiz sessions | id, user_id, quiz_type, status, session_data |
| quiz_results | Completed quiz results | id, user_id, score, accuracy, duration_sec |
| quiz_answers | Individual answers | id, result_id, question_id, is_correct, time_spent_sec |
| Table | Description | Key Columns |
|---|---|---|
| leaderboard | Rankings | id, user_id, period, subject, points |
| badges | Achievement badges | id, code, title, xp_value |
| analytics | Performance metrics | id, user_id, metric_name, metric_value, recorded_at |
| bookmarked_questions | Saved questions | user_id, question_id |
| Table | Description | Key Columns |
|---|---|---|
| mistake_book | Wrong questions tracker | user_id, question_id, wrong_count, retry_count |
| revision_schedule | Spaced repetition | user_id, question_id, stage_day, due_at, status |
| concept_cards | Study material | subject, topic, theory, formulas, definitions |
| Table | Description | Key Columns |
|---|---|---|
| batches | Student groups | id, name, batch_type, department |
| assignments | Faculty assignments | id, title, batch_id, quiz_type, question_ids, due_at |
| assignment_submissions | Student submissions | assignment_id, user_id, result_id, submitted_at |
| notifications | System notifications | user_id, title, body, category, is_read |
| certificates | Achievement certificates | user_id, title, file_path |
| Table | Description |
|---|---|
| app_settings | App configuration (key-value store) |
| admin_logs | Admin action audit trail |
| update_history | Question bank update logs |
users ──┬── quiz_results ─── quiz_answers
├── quiz_sessions
├── bookmarked_questions ─── questions
├── mistake_book ─── questions
├── revision_schedule ─── questions
├── assignments
├── assignment_submissions
├── certificates
├── notifications
├── analytics
└── leaderboard
batches ──┬── users
├── assignments
└── leaderboard
The application includes a PyInstaller spec file for creating distributable executables.
# Install PyInstaller (already in requirements.txt)
pip install pyinstaller
# Build executable
pyinstaller pyinstaller.spec
# Output location
dist/MiningExamPrep.exe# Build
pyinstaller pyinstaller.spec
# Output
dist/MiningExamPrep.app# Build
pyinstaller pyinstaller.spec
# Output
dist/MiningExamPrep- Test executable on clean machine
- Verify database creation on first run
- Test all features (quiz, analytics, backups)
- Include README in dist folder
- Create installer (Inno Setup for Windows, DMG for macOS)
- Sign executable (optional but recommended)
- Single
.exe/.appfile - No Python installation required
- All dependencies bundled
- Multiple instances on local network
- Leaderboard synchronization enabled
- Shared question updates via manifests
- Central database (optional)
- Faculty admin accounts
- Batch-based student organization
mining-quiz-app/
│
├── 📄 main.py # Application entry point
├── 📄 requirements.txt # Python dependencies
├── 📄 pyinstaller.spec # PyInstaller build configuration
├── 📄 README.md # This file
│
├── 📁 app/ # Main application package
│ ├── 📄 __init__.py # Package initialization, logging setup
│ ├── 📄 bootstrap.py # Dependency injection, app startup
│ ├── 📄 config.py # Configuration constants
│ │
│ ├── 📁 auth/ # Authentication system
│ │ ├── 📄 __init__.py
│ │ └── 📄 service.py # AuthService (login, register, recovery)
│ │
│ ├── 📁 database/ # Database layer
│ │ ├── 📄 __init__.py
│ │ └── 📄 db.py # Database class (schema, migrations, CRUD)
│ │
│ ├── 📁 models/ # Data models
│ │ ├── 📄 __init__.py
│ │ ├── 📄 entities.py # User, Question, QuizResult dataclasses
│ │ └── 📄 constants.py # App constants, mining knowledge base
│ │
│ ├── 📁 services/ # Business logic services
│ │ ├── 📄 __init__.py
│ │ ├── 📄 quiz_engine.py # Quiz logic, session management
│ │ ├── 📄 question_manager.py # Question CRUD, filtering, import
│ │ ├── 📄 analytics.py # Performance analytics, metrics
│ │ ├── 📄 leaderboard.py # Ranking, points calculation
│ │ ├── 📄 learning_service.py # Concept cards, spaced repetition
│ │ ├── 📄 faculty_service.py # Assignment creation, monitoring
│ │ ├── 📄 report_service.py # Report generation (Excel/PDF)
│ │ ├── 📄 backup_security.py # Backup creation, restore
│ │ ├── 📄 notifications.py # Notification management
│ │ ├── 📄 admin_panel.py # Admin operations, logs
│ │ ├── 📄 lan_service.py # LAN broadcasting, sync
│ │ ├── 📄 update_service.py # Question bank updates
│ │ └── 📄 export_utility.py # Export helpers
│ │
│ ├── 📁 ui/ # User interface components
│ │ ├── 📄 __init__.py
│ │ ├── 📄 theme.py # Dark theme stylesheet
│ │ ├── 📄 assets.py # Asset loading, icon management
│ │ ├── 📄 components.py # Reusable UI components
│ │ ├── 📄 login_window.py # Login/register interface
│ │ ├── 📄 main_window.py # Main application window
│ │ ├── 📄 dashboard_widget.py # Dashboard with stats
│ │ ├── 📄 quiz_widget.py # Quiz interface
│ │ ├── 📄 learning_widget.py # Learning tools UI
│ │ ├── 📄 question_bank_widget.py # Question management UI
│ │ ├── 📄 analytics_widget.py # Analytics charts
│ │ ├── 📄 leaderboard_widget.py # Leaderboard display
│ │ ├── 📄 reports_widget.py # Reports generation UI
│ │ ├── 📄 faculty_widget.py # Faculty features UI
│ │ ├── 📄 update_widget.py # Update management UI
│ │ └── 📄 chart_widgets.py # Custom chart components
│ │
│ └── 📁 utils/ # Utility functions
│ └── 📄 __init__.py
│
├── 📁 assets/ # Application assets
│ ├── 📁 default/ # Default fallback assets
│ ├── 📁 icons/ # Application icons
│ ├── 📁 photos/ # User profile photos
│ └── 📁 wallpapers/ # Background images
│
├── 📁 data/ # Application data
│ ├── 📄 mining_quiz.db # SQLite database (auto-created)
│ ├── 📁 backups/ # Automatic database backups
│ ├── 📁 certificates/ # Generated certificates
│ ├── 📁 exports/ # Exported reports
│ ├── 📁 logs/ # Application logs
│ ├── 📁 reports/ # Generated reports
│ └── 📁 updates/ # Question bank update manifests
│ ├── 📄 manifest.json # Update manifest
│ └── 📁 patches/ # Question patch files
│
├── 📁 tests/ # Test suite
│ ├── 📄 conftest.py # Pytest configuration
│ ├── 📄 test_auth_and_quiz_flow.py # Authentication & quiz tests
│ ├── 📄 test_question_manager.py # Question management tests
│ └── 📄 test_smoke.py # Smoke tests
│
├── 📁 ui/ # Qt Designer UI files
│ ├── 📄 dashboard.ui # Dashboard layout
│ └── 📄 login.ui # Login layout
│
└── 📁 .vscode/ # VS Code settings (optional)
| Module | Files | Purpose |
|---|---|---|
| app | 38 Python files | Core application logic |
| app/ui | 16 files | PyQt6 interface widgets |
| app/services | 14 files | Business logic services |
| app/models | 3 files | Data models & constants |
| app/auth | 2 files | Authentication system |
| app/database | 2 files | Database layer |
| assets | Images/Icons | UI resources |
| data | Database/Logs | User data storage |
| tests | 4 files | Unit & integration tests |
Problem: ImportError: No module named 'PyQt6'
Solution:
pip install -r requirements.txtProblem: Database initialization failed
Solution:
- Ensure
data/directory has write permissions - Delete
data/mining_quiz.dband restart (will recreate) - Check disk space availability
Problem: Password rejected after recent reinstall
Solution:
- Database may have been recreated
- Use default admin credentials:
admin/admin@123A - Check
data/logs/mining_exam_prep.logfor errors
Problem: Analytics page shows empty charts
Solution:
pip install --upgrade matplotlibProblem: Leaderboard not syncing across network
Solution:
- Ensure all computers on same network
- Check firewall allows port
45678 - Verify
LAN_BROADCAST_PORTin config.py matches across devices
Problem: Cannot restore from backup
Solution:
- Verify backup file exists in
data/backups/ - Backup files are SQLite databases with
.dbextension - Manually copy backup to
data/mining_quiz.dbif needed
Problem: "This app can't run on your PC"
Solution:
- Rebuild executable on same architecture (x64/x86)
- Install Visual C++ Redistributable
- Run as Administrator
Enable detailed logging:
# In app/__init__.py
import logging
logging.basicConfig(level=logging.DEBUG)Logs location: data/logs/mining_exam_prep.log
The app automatically saves:
- ✅ Quiz drafts (resume later)
- ✅ UI state (window position, tabs)
- ✅ Auto-backups (every 15 min)
After a crash:
- Restart application
- Check notification for recovery message
- Resume from last saved state
Q: Is internet required?
A: No, the app is fully offline. Internet only needed for optional LAN sync.
Q: Can I use this on multiple devices?
A: Yes, copy the data/ folder to sync your progress, or use LAN sync feature.
Q: How do I reset my password?
A: Use "Forgot Password" on login screen → Answer security question → Set new password.
Q: Can I import my own questions?
A: Yes (Faculty/Admin only). Use Excel import in Question Bank → Bulk Import.
Q: Which Python version is required?
A: Python 3.10 or higher. Check with python --version.
Q: Can I change the database location?
A: Yes, modify DB_PATH in app/config.py.
Q: How are passwords stored?
A: SHA-256 hashed with unique salts per user. Never stored in plain text.
Q: What's the database size limit?
A: SQLite supports databases up to 281 TB. Typical usage: 10-50 MB.
Q: Can I run multiple instances?
A: Not recommended on same machine (database locking). Use different data directories.
Q: How does spaced repetition work?
A: Reviews scheduled at: 1, 3, 7, 14, 30 days after initial learning.
Q: What triggers a badge award?
A: Achievements like "First Quiz", "100 Questions", "10 Day Streak", etc.
Q: Can faculty create custom quizzes?
A: Yes, via Assignments → Create Assignment → Select questions.
Q: How are leaderboard rankings calculated?
A: Based on total score (correct answers × marks - wrong × negative marks).
Q: Can I export my performance data?
A: Yes, Reports → Generate Report → Choose format (Excel/PDF).
- Mobile App: Flutter companion app for iOS/Android
- Cloud Sync: Optional cloud backup & sync
- Video Explanations: Embed video solutions for questions
- Voice Mode: Voice-based quiz navigation (accessibility)
- Social Features: Friend system, challenge friends
- AI Question Generation: Auto-generate questions using LLM
- Adaptive Learning: AI-powered personalized question selection
- Multi-Language Support: Hindi, regional languages
- Advanced Analytics: Predictive performance modeling
- Collaboration Mode: Real-time multiplayer quizzes
- Web Version: Browser-based access
- Integration: Canvas LMS, Moodle compatibility
- Advanced Gamification: Guilds, tournaments, seasons
- Marketplace: Community question banks
- Enterprise: Multi-institution management
Vote on features at Discussions
We welcome contributions! Here's how you can help:
- Report Bugs: Open an issue with details
- Suggest Features: Use Discussions tab
- Submit Code: Fork, branch, PR
- Improve Docs: Typos, clarity, examples
- Add Questions: Submit mining engineering questions
# Fork repository
git clone https://github.com/YOUR_USERNAME/mining-quiz-app.git
cd mining-quiz-app
# Create feature branch
git checkout -b feature/amazing-feature
# Install dev dependencies
pip install -r requirements.txt
pip install pytest black flake8
# Make changes, test
pytest tests/
# Format code
black app/
flake8 app/
# Commit
git commit -m "Add amazing feature"
# Push
git push origin feature/amazing-feature
# Open Pull Request- Formatting: Black (line length 120)
- Linting: Flake8
- Type Hints: Encouraged (Python 3.10+ syntax)
- Docstrings: Google style
- Testing: pytest for new features
- Code follows project style
- Tests added for new features
- Documentation updated
- No breaking changes (or clearly documented)
- Commits are atomic and well-described
Be respectful, inclusive, and constructive. See CODE_OF_CONDUCT.md.
This project is licensed under the MIT License - see the LICENSE file for details.
- ✅ Commercial use
- ✅ Modification
- ✅ Distribution
- ✅ Private use
⚠️ Liability disclaimer⚠️ Warranty disclaimer
[Your Name]
🔗 GitHub: @yourusername
📧 Email: your.email@example.com
- PyQt6 - Desktop UI framework
- Matplotlib - Chart visualization
- Pandas - Data processing
- SQLite - Embedded database
- Mining Engineering faculty for domain expertise
- PyQt community for UI guidance
- All beta testers and contributors
- University of XYZ for supporting this project
- Student contributors: [Name1], [Name2], [Name3]
- Open-source community
- 📖 Documentation: Wiki
- 💬 Discussions: GitHub Discussions
- 🐛 Bug Reports: Issues
- 📧 Email: support@miningexamprep.com
- 🌟 Star this repo if you find it useful!
- 🐦 Follow updates on Twitter: @MiningExamPrep
- 💼 LinkedIn: Mining Exam Prep
Made with ❤️ for Mining Engineering Students
⭐ Star us on GitHub — it motivates us to improve!