Skip to content

README.md

Latest commit

 

History

History
337 lines (245 loc) · 8.94 KB

README.md

File metadata and controls

337 lines (245 loc) · 8.94 KB
Raw

Quiz-App

A modern, interactive quiz platform built with React and FastAPI. Test your knowledge in Python, Java, and Technology with engaging quizzes featuring multiple-choice questions and Parsons problems (code ordering challenges).

✨ Features

  • 🔐 GitHub OAuth Authentication - Secure login with your GitHub account
  • 📚 Multiple Quiz Categories - Python, Java, and Technology quizzes
  • 🎯 Interactive Question Types
    • Multiple choice questions
    • Parsons problems (drag-and-drop code ordering)
    • Output prediction questions (predict code output)
    • Debugging questions (identify and fix bugs)
    • Fill in the blank questions (complete code snippets)
    • Free response questions (type your answer)
    • Faded Parsons (drag-and-drop with fixed lines)
  • 🏆 Leaderboard System - Track your progress and compete globally
  • 📊 Personal Dashboard - View your stats, quiz history, and skills profile
  • 🎨 Modern UI/UX - Space-themed login with animated backgrounds
  • ♿ Accessibility - Built with accessibility best practices
  • 🐳 Docker Support - Easy deployment with Docker Compose

🚀 Quick Start

Prerequisites

  • Node.js 18+ and npm
  • Python 3.10+
  • GitHub OAuth App (for authentication)

Option 1: Docker Compose (Recommended)

The easiest way to run the entire application:

# 1. Clone the repository
git clone https://github.com/dotnetdork/Quiz-App.git
cd Quiz-App

# 2. Copy environment template and configure
cp .env-template .env
# Edit .env with your GitHub OAuth credentials

# 3. Start all services
docker-compose up --build

# Access the app at http://localhost:8000

Option 2: Manual Setup

Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GITHUB_CLIENT_ID="your_github_client_id"
export GITHUB_CLIENT_SECRET="your_github_client_secret"
export GITHUB_REDIRECT_URI="http://localhost:8000/auth/callback"
export SECRET_KEY="your_secret_key_here"  # Generate with: python -c "import secrets; print(secrets.token_hex(32))"

# Run database migrations (if needed)
python migrate_db.py

# Start the FastAPI server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

# Open a new terminal and navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start the development server
npm start

# The app will open at http://localhost:3000

🔑 Setting Up GitHub OAuth

  1. Go to GitHub Settings → Developer settings → OAuth Apps → New OAuth App
  2. Fill in the application details:
    • Application name: Quiz-App (or your preferred name)
    • Homepage URL: http://localhost:8000 (for local development)
    • Authorization callback URL: http://localhost:8000/auth/callback
  3. Click "Register application"
  4. Copy the Client ID and generate a Client Secret
  5. Add these credentials to your .env file or environment variables

📊 Database

The application uses SQLite for data storage with the following tables:

  • users - User profiles from GitHub OAuth
  • scores - Quiz attempt records with timestamps
  • quiz_history - Detailed question-by-question results

Database Location

  • Development: backend/quiz_app.db
  • Docker: Persisted in quiz_data volume

Accessing the Database

# Using SQLite CLI
sqlite3 backend/quiz_app.db

# View tables
.tables

# Query users
SELECT * FROM users;

# Query scores
SELECT * FROM scores ORDER BY timestamp DESC LIMIT 10;

Database Migrations

If schema changes are needed:

cd backend
python migrate_db.py

🏗️ Project Structure

Quiz-App/
├── frontend/                 # React frontend application
│   ├── public/              # Static assets
│   ├── src/
│   │   ├── components/      # Reusable React components
│   │   ├── pages/           # Page components (Login, Dashboard, Quiz)
│   │   ├── utils/           # Utility functions and custom hooks
│   │   ├── App.js           # Main application component
│   │   └── api.js           # API client configuration
│   └── package.json
├── backend/                 # FastAPI backend application
│   ├── main.py              # FastAPI application entry point
│   ├── auth.py              # GitHub OAuth authentication
│   ├── database.py          # Database models and session management
│   ├── models.py            # SQLAlchemy ORM models
│   ├── quiz_routes.py       # Quiz API endpoints
│   ├── leaderboard_routes.py # Leaderboard API endpoints
│   ├── questions.yaml       # Quiz questions database
│   └── requirements.txt
├── docker/                  # Docker configuration files
├── docs/                    # Documentation
├── .env-template           # Environment variables template
└── docker-compose.yml      # Docker Compose configuration

🧪 Running Tests

Frontend Tests

cd frontend
npm test

Backend Tests

cd backend
pytest

🛠️ Development

Frontend Development

The frontend uses React 19 with React Router for navigation. Key technologies:

  • React Router - Client-side routing
  • @dnd-kit - Drag and drop for Parsons problems

Hot reload is enabled for development:

cd frontend
npm start

Backend Development

The backend uses FastAPI with async support. Key features:

  • SQLAlchemy - ORM for database operations
  • Authlib - OAuth 2.0 client
  • PyYAML - Quiz configuration parsing

Enable auto-reload during development:

cd backend
uvicorn main:app --reload

API Documentation

FastAPI provides interactive API documentation:

📝 Adding New Quizzes

Quizzes are defined in backend/questions.yaml. Example structure:

- id: "python-basics-1"
  title: "Python Basics - Variables and Types"
  description: "Test your knowledge of Python variables, data types, and basic operations"
  category: "python"
  questions:
    - id: "pybasic-1"
      type: "multiple-choice"
      question: "What is the output of: print(type(42))?"
      options:
        - "<class 'int'>"
        - "<class 'float'>"
        - "<class 'str'>"
        - "42"
      correct_answer: 0
    - id: "pybasic-2"
      type: "parsons"
      question: "Arrange these lines to create a function that returns the square of a number:"
      blocks:
        - "def square(n):"
        - "    result = n * n"
        - "    return result"

After adding quizzes, restart the backend server.

🚀 Deployment

Production Build

# Build frontend
cd frontend
npm run build

# The build output is in frontend/build/
# FastAPI will automatically serve this if the build directory exists

Environment Variables for Production

# Required environment variables
GITHUB_CLIENT_ID=your_production_client_id
GITHUB_CLIENT_SECRET=your_production_client_secret
GITHUB_REDIRECT_URI=https://yourdomain.com/auth/callback
SECRET_KEY=your_production_secret_key
FRONTEND_URL=https://yourdomain.com  # Optional, for CORS

Docker Production Deployment

docker-compose -f docker-compose.prod.yml up -d

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Code Style

  • Frontend: Follow ESLint rules configured in the project
  • Backend: Follow PEP 8 style guide
  • Commits: Use conventional commit messages

📄 License

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

👥 Authors

🐛 Issues and Support

Found a bug or need help?

  • Open an issue on GitHub Issues
  • Check existing issues first to avoid duplicates
  • Provide detailed information about the problem

🎓 Learning Resources

This project demonstrates:

  • React hooks and modern React patterns
  • FastAPI async programming
  • OAuth 2.0 authentication flow
  • RESTful API design
  • SQLAlchemy ORM usage
  • Docker containerization
  • Frontend-backend integration

🔗 Related Links

Built with ❤️ by The League of Amazing Programmers