8000 GitHub - A1exKH/ILQP: Interactive Learning & Quiz Platform · GitHub
[go: up one dir, main page]

Skip to content
A1exKHPublic

About

Interactive Learning & Quiz Platform

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Interactive Learning & Quiz Platform (ILQP)

License: MIT Python FastAPI React TypeScript MongoDB Backend CI

A modern, full-stack flashcard and quiz creation platform designed for interactive learning.

Users can build custom decks, tag them by topic or language, take timed practice quizzes with immediate feedback, and track learning progress using detailed analytics.

Application Preview

Main Catalog View Quiz Taker Experience
Main Page View Quiz Taker View
Analytics & Progress Dashboard Custom Deck Builder
Analytics Dashboard Custom Deck Builder

For full user guides and high-resolution workflows, visit the ILQP Project Wiki.

Core Features

  • Deck & Card Management (CRUD): Create, edit, and delete custom quiz decks with multiple-choice and short-answer questions.
  • Interactive Quiz Runner: Dynamic React state engine tracking elapsed time, instant answer validation, and score calculation.
  • Analytics & Progress Dashboard: Real-time data visualization showing pass/fail rates, completion speed, and topic mastery breakdown.
  • High-Performance MongoDB Engine: Optimized compound B-tree indexes ensuring sub-millisecond query responses across thousands of decks and user attempts.

Architecture Overview

┌──────────────────────────┐      REST API (JSON)      ┌─────────────────────────┐
│     React + Vite         │ ────────────────────────> │     FastAPI Backend     │
│   (TypeScript / Tailwind)│ <──────────────────────── │  (Python / Pydantic)    │
└──────────────────────────┘                           └────────────┬────────────┘
                                                                    │ Motor Async
                                                                    ▼
                                                       ┌─────────────────────────┐
                                                       │   MongoDB Atlas Cluster │
                                                       │  (Compound Indexes)     │
                                                       └─────────────────────────┘

Database Architecture & Index Optimization

The database uses Async Motor driver queries over MongoDB Atlas. To support fast catalog filtering and chronological history rendering under heavy load, two compound indexes are enforced at startup:

  1. Deck Filtering Index: { category: 1, difficulty: 1 }
  2. User History Index: { userId: 1, createdAt: -1 }

Benchmark Execution Stats

Tested against 10,000 seeded mock documents:

Query Metric Baseline (Unindexed) Optimized (Compound Index) Performance Gain
Scan Strategy COLLSCAN (Full Table) FIXSCAN (B-Tree Index) Direct Lookup
Documents Examined 10,000 docs ~12 docs 99.8% reduction
Execution Speed ~68 ms ~2 ms ~34x Speedup

REST API Specifications

Interactive Swagger API documentation is available at /docs (e.g., http://localhost:8010/docs).

1. Decks & Questions (/api/decks)

Method Endpoint Description Request Body / Query
GET /api/decks Fetch all decks (supports category/difficulty filters) Query: ?category=spanish&difficulty=Beginner
GET /api/decks/:id Get single deck details (includes embedded questions) None
POST /api/decks Create a new quiz deck with questions DeckCreateSchema
PUT /api/decks/:id Update deck metadata or question list Updated Deck Object
DELETE /api/decks/:id Delete a deck and its associated attempts None

2. Quiz Engine & Submissions (/api/attempts)

Method Endpoint Description Request Body /Query
POST /api/attempts Submit completed quiz attempt & calculate score { deckId, answers, completionTimeMs }
GET /api/attempts/user/:userId Get full quiz history for a specific user Query: ?limit=10
GET /api/attempts/deck/:deckId Get historical results for a specific deck None

3. Analytics & Progress (/api/analytics)

Method Endpoint Description Response Data
GET /api/analytics/dashboard Aggregated user stats across all quizzes Total quizzes taken, average score, total time spent, mastery breakdown by category

Quick Start & Local Setup

Prerequisites

  • Node.js (v20+) & npm
  • Python (v3.12+)
  • MongoDB Atlas cluster or local instance

1. Automated Launch (Recommended)

In root directory, grant execution permissions and start backend & frontend:

chmod +x scripts/*.sh

# Terminal 1: Start FastAPI Backend (Port 8010)
./scripts/start-backend.sh

# Terminal 2: Start React Frontend (Port 5173)
./scripts/start-frontend.sh

2. Manual Step-by-Step Setup

Backend Setup

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn app.main:app --reload --port 8010

Frontend Setup

cd frontend
npm install
npm run dev

Testing & Quality Assurance

The ILQP backend features a comprehensive test suite built with Pytest, HTTPX, and Pytest-Cov, covering pure business logic unit tests, asynchronous FastAPI endpoint integration tests, and MongoDB database interactions.

Test Suite Architecture

  1. Unit Tests (tests/test_quiz_engine.py)

    • Quiz Scoring Logic: Verifies accurate percentage calculations across 100% scores, partial credit, and empty submission edge cases.
    • Timing Validation: Tests average time calculation per question and validates realistic completion time bounds.
  2. API Route Integration Tests (tests/test_decks_api.py, tests/test_attempts_api.py, tests/test_analytics_api.py)

    • Deck Management (/api/decks): Validates deck creation payloads, required schema fields, and category/difficulty query filtering.
    • Quiz Submissions (/api/attempts): Tests quiz attempt logging, scoring computation, user quiz history retrieval, and error handling for non-existent resources.
    • Analytics Dashboard (/api/analytics/dashboard): Verifies aggregated user stats (total quizzes, average scores, time spent) and safeguards against division-by-zero for zero-history users.

Running Tests Locally

To run the test suite locally in your development environment:

  1. Activate your virtual environment:
cd backend
source venv/bin/activate
  1. Run Pytest with coverage reporting:
pytest --cov=app --cov-report=term-missing -v
  1. View coverage report:
# Coverage summary will be displayed in the terminal, highlighting untested lines.
# For a detailed HTML report:
coverage html
# Open the generated report in your browser:
open htmlcov/index.html
  1. Run tests against a live MongoDB instance:
    • Ensure your MongoDB Atlas cluster is running and accessible.
    • Set the MONGO_URI environment variable to point to your database before executing tests:
export MONGO_URI="mongodb+srv://<username>:<password>@cluster0.mongodb.net/test?retryWrites=true&w=majority"
pytest --cov=app --cov-report=term-missing -v
  1. Run tests in isolation with a temporary MongoDB container:
    • If you prefer not to use your production database, you can spin up a temporary MongoDB container for testing:
docker run --name ilqp-test-mongo -d -p 27017:27017
export MONGO_URI="mongodb://localhost:27017/test"
pytest --cov=app --cov-report=term-missing -v
docker stop ilqp-test-mongo && docker rm ilqp-test-mongo
  1. Continuous Integration (CI) Testing:

    • All tests are automatically executed on every push and pull request to the main and development branches via GitHub Actions. The CI pipeline ensures that all tests pass and maintains high code quality standards.
  2. How to Run Pytest and View the Printed Output

    • To see detailed output during test execution, use the -s flag with pytest:
pytest -s --cov=app --cov-report=term-missing -v

Code Coverage Metrics

We use pytest-cov to track line-by-line test coverage across all application routers, models, and core engines.

Our CI pipeline enforces clean execution and maintains high test coverage standards across core business features.

CI/CD Automation (GitHub Actions)

All tests are executed automatically on every push and pull request to main and development branches via GitHub Actions (.github/workflows/backend-ci.yml).

  • Environment: Runs on isolated Ubuntu runners with Python 3.12.
  • Database Service: Spins up a live MongoDB service container (mongo:latest) on port 27017 to ensure all database-backed integration tests execute against a real database instance rather than mocks.

Cloud Architecture & Deployment (CI/CD)

The ILQP backend is fully containerized and deployed automatically to Google Cloud Platform (GCP) using a modern, zero-downtime serverless architecture.

Infrastructure Overview

  • Hosting Platform: Google Cloud Run (Serverless container runtime that automatically scales up under load and scales down to zero when idle).
  • Container Registry: Google Cloud Artifact Registry (Stores versioned Docker images securely within GCP).
  • Database: MongoDB Atlas (Cloud-hosted distributed database cluster with secure TLS/SSL connectivity).

CI/CD Pipeline (GitHub Actions)

We use GitHub Actions (.github/workflows/backend-ci.yml) to achieve fully automated Continuous Integration and Continuous Deployment (CI/CD) on every push to the main branch.

Pipeline Stages:

  1. Automated Testing: Spins up an ephemeral mongo:latest service container in an isolated runner, installing dependencies and running the complete Pytest and pytest-cov test suite.
  2. Keyless OIDC Authentication: Authenticates securely with Google Cloud using Workload Identity Federation (WIF), eliminating the security risks of long-lived service account JSON keys.
  3. Docker Build & Push: Packages the FastAPI application using a custom multi-step Dockerfile (optimized with python:3.12-slim and system ca-certificates for secure TLS handshakes) and pushes the image to GCP Artifact Registry.
  4. Cloud Run Deployment: Automatically deploys the latest container revision to Google Cloud Run, injecting production environment secrets securely at runtime.

Project Documentation & Standards

Maintainer & Contact

About

Interactive Learning & Quiz Platform

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0