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.
| Main Catalog View | Quiz Taker Experience |
|---|---|
| Analytics & Progress Dashboard | Custom Deck Builder |
|---|---|
For full user guides and high-resolution workflows, visit the ILQP Project Wiki.
- 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.
┌──────────────────────────┐ REST API (JSON) ┌─────────────────────────┐
│ React + Vite │ ────────────────────────> │ FastAPI Backend │
│ (TypeScript / Tailwind)│ <──────────────────────── │ (Python / Pydantic) │
└──────────────────────────┘ └────────────┬────────────┘
│ Motor Async
▼
┌─────────────────────────┐
│ MongoDB Atlas Cluster │
│ (Compound Indexes) │
└─────────────────────────┘
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:
- Deck Filtering Index: { category: 1, difficulty: 1 }
- User History Index: { userId: 1, createdAt: -1 }
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 |
Interactive Swagger API documentation is available at /docs (e.g., http://localhost:8010/docs).
| 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 |
| 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 |
| 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 |
- Node.js (v20+) & npm
- Python (v3.12+)
- MongoDB Atlas cluster or local instance
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.shcd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn app.main:app --reload --port 8010cd frontend
npm install
npm run devThe 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.
-
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.
-
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.
- Deck Management (
To run the test suite locally in your development environment:
- Activate your virtual environment:
cd backend
source venv/bin/activate- Run Pytest with coverage reporting:
pytest --cov=app --cov-report=term-missing -v- 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- Run tests against a live MongoDB instance:
- Ensure your MongoDB Atlas cluster is running and accessible.
- Set the
MONGO_URIenvironment 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- 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-
Continuous Integration (CI) Testing:
- All tests are automatically executed on every push and pull request to the
mainanddevelopmentbranches via GitHub Actions. The CI pipeline ensures that all tests pass and maintains high code quality standards.
- All tests are automatically executed on every push and pull request to the
-
How to Run Pytest and View the Printed Output
- To see detailed output during test execution, use the
-sflag with pytest:
- To see detailed output during test execution, use the
pytest -s --cov=app --cov-report=term-missing -vWe 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.
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.
The ILQP backend is fully containerized and deployed automatically to Google Cloud Platform (GCP) using a modern, zero-downtime serverless architecture.
- 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).
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.
- Automated Testing: Spins up an ephemeral
mongo:latestservice container in an isolated runner, installing dependencies and running the complete Pytest andpytest-covtest suite. - Keyless OIDC Authentication: Authenticates securely with Google Cloud using Workload Identity Federation (WIF), eliminating the security risks of long-lived service account JSON keys.
- Docker Build & Push: Packages the FastAPI application using a custom multi-step
Dockerfile(optimized withpython:3.12-slimand systemca-certificatesfor secure TLS handshakes) and pushes the image to GCP Artifact Registry. - Cloud Run Deployment: Automatically deploys the latest container revision to Google Cloud Run, injecting production environment secrets securely at runtime.
- Code of Conduct
- Contributing Guidelines
- Security Policy
- Accessibility Statement
- MIT License
- Project Wiki
- Developer: Aliaksandr Kulinkovich (A1exKH)
- Email: alexander.kulinkovich@gmail.com
- GitHub: @A1exKH