Quizzical is a backend-focused project that turns raw documents into structured quizzes using LLMs. It’s less about “using AI” and more about building a system that actually supports it — async processing, job orchestration, and a clean pipeline from input → generation → storage.
Quizzical takes source material (PDFs, text, etc.), processes it, and generates quizzes automatically.
Users can:
- Upload documents 📄
- Generate quizzes from them ⚙️
- Retrieve structured questions 📊
- Control difficulty and size 🎯
At its core, everything revolves around a generation job.
- User requests a quiz
- A job is created and stored
- A background worker picks it up
- Document content is chunked & retrieved
- LLM generates questions
- Results are saved and exposed via API
This avoids blocking requests and keeps the system responsive even with heavy LLM calls.
- Django — core framework
- Django REST Framework — API layer
- Celery — background task queue
- Redis — broker for job distribution
- SQLite (development)
- PostgreSQL (target for production)
- Embeddings — semantic retrieval of document chunks
- LLM APIs — question generation
- JWT (JSON Web Tokens) — stateless authentication
The project is split into focused Django apps:
- accounts → authentication & users
- documents → upload, parsing, chunking
- quizzes → quiz + question storage
- generation → job orchestration + Celery integration
The generation app ties everything together — it creates jobs, triggers workers, and connects documents to quiz output.
Quiz creation is not handled in a single request. It’s tracked as a job:
- easier to monitor
- retry on failure
- scalable with more workers
Anything expensive (LLM calls, embeddings) runs through Celery. Sync logic is only a stepping stone.
Instead of passing full documents:
- content is chunked
- embedded
- selectively retrieved
This improves quality and keeps token usage under control.
Each app handles one concern. No mixing of responsibilities, which keeps the codebase maintainable.
- Users only access their own documents and quizzes
- All write operations require authentication
- Public access is minimal by design
Built iteratively:
- start simple → evolve into async
- understand infra (queues, workers, jobs)
- prioritize clarity over premature optimization
- Job status tracking (polling / WebSockets)
- Better prompt engineering
- More question formats (MCQ, open-ended, etc.)
- Lightweight frontend
- Sharing & collaboration
In progress — focus is on solidifying the generation pipeline and system design.