Quizy - Technical Design & API Contract

himanshu — Sun, 13 Jul 2025 20:53:16 +0000

✅ Functional Requirements (FRD) – Quizy

🔐 User Authentication & Accounts

User can register with name, email, and password.
User can login and receive a JWT token + refresh token.
User can logout (token invalidation if stored server-side).
User can reset password via:
- Forgot Password (email trigger)
- Reset Password (token-based form)
User authentication must be secure and token-based (JWT).
Authenticated user session should be persisted client-side.

📚 Question Bank Management

User can create multiple question banks.
Each question bank:
- Has a title and description.
- Belongs to one user.
- Contains multiple question sets (from PDF uploads).

📄 Question Set Upload & Processing

User can upload a PDF to a specific question bank.
Each PDF is stored as a question set.
After upload:
- The system starts a background job to parse questions from the PDF.
- Questions are stored with:
- Text
- 4 options (a, b, c, d)
- Correct answer
- Explanation
- Tags
User can poll /status endpoint to check processing state: PENDING, PROCESSING, DONE, FAILED.
Extracted questions can be fetched and browsed.

🧪 Test Creation & Series

Users can group multiple tests under a Test Series.
A test can be created by selecting questions from:
- One or more question sets
Each test has:
- Title, description
- List of question IDs
- Belongs to a test series and a user

📝 Test Taking (Attempt Lifecycle)

User can start a test attempt (one active per test).
During the test:
- A scrollable, paginated view shows the questions
- User can:
- Select one option (a, b, c, d)
- Mark question for review
- Navigate across questions
User can submit the test:
- Score is calculated
- All question attempts are recorded
System returns:
- Final score
- Detailed breakdown with:
- Selected answer
- Correct answer
- Explanation

📈 Tracking & Analytics

Each test attempt is stored in an Attempt history table.
Users can:
- View past test scores
- Track progress (score vs. time)
- See leaderboard (based on avg scores across users)

🏷️ Tag-based Features

Questions can be tagged (string[]).
User can filter or select questions by tag during:
- Test creation
- Reviewing questions
- Creating topic-specific tests (future scope)

🧰 Admin/Moderation (Future Scope)

System admin may get dashboard to:
- Manage flagged questions
- Approve/reject user-uploaded questions (if public bank)
- Monitor processing failures

🔁 System Functional Notes

All uploaded PDFs are stored via ActiveStorage + AWS S3.
PDF parsing job runs asynchronously via Sidekiq.
Test submissions are atomic (submitted only once per attempt).
Long-poll or polling status for PDF jobs will hit: /api/question-sets/:id/status

Quizy - Quiz Application (API-First Design)

Stack Overview

Frontend: React (with Redux or Zustand for state management) [backend might change]
Backend: Node.js (Express.js) or ROR
Database: PostgreSQL (via Prisma ORM)
Authentication: JWT + Refresh Token
File Handling: AWS S3
PDF Extraction: Python microservice (FastAPI)
Communication: REST + Long Polling

Data Models (PostgreSQL via Prisma)

User

id: string (UUID)
email: string
passwordHash: string
name: string
createdAt: Date
updatedAt: Date

QuestionBank

id: string
userId: string (FK -> User)
title: string
description: string
createdAt: Date

QuestionSet

id: string
questionBankId: string (FK -> QuestionBank)
title: string
sourcePdfUrl: string
status: enum('PENDING', 'PROCESSING', 'DONE', 'FAILED')
createdAt: Date

Question

id: string
questionSetId: string (FK -> QuestionSet)
text: string
options: { a: string, b: string, c: string, d: string }
correctAnswer: 'a' | 'b' | 'c' | 'd'
explanation: string
tags: string[]

TestSeries

id: string
userId: string
title: string

Test

id: string
testSeriesId: string
userId: string
title: string
description: string
questionIds: string[]
createdAt: Date

Attempt

id: string
testId: string
userId: string
questionResponses: {
  questionId: string,
  selectedOption: 'a' | 'b' | 'c' | 'd' | null,
  markedForReview: boolean
}[]
score: number
startedAt: Date
submittedAt: Date

API Contracts

Authentication

POST `/api/auth/register`

Registers a user.

{ "email": "...", "password": "...", "name": "..." }

Response:

{ "token": "...", "refreshToken": "..." }

POST `/api/auth/login`

Logs in a user.

{ "email": "...", "password": "..." }

Response: Same as above

POST `/api/auth/refresh`

Refreshes the JWT.

{ "refreshToken": "..." }

POST `/api/auth/forgot`

Starts password reset process.

{ "email": "..." }

POST `/api/auth/reset`

Resets password.

{ "token": "...", "newPassword": "..." }

Question Bank

POST `/api/question-banks`

Creates a question bank.

{ "title": "...", "description": "..." }

GET `/api/question-banks`

Returns all user's question banks.

Question Set & PDF Upload

POST `/api/question-banks/:id/question-sets`

Upload PDF to a question bank.
Form-Data:

title: string
pdf: File

Response:

{ "id": "...", "status": "PENDING" }

GET `/api/question-sets/:id/status`

Get PDF processing status (long-poll).

{ "status": "PROCESSING" | "DONE" | "FAILED" }

GET `/api/question-sets/:id/questions`

Get parsed questions from a question set.

[{
  "id": "...",
  "text": "...",
  "options": { "a": "...", "b": "...", "c": "...", "d": "..." },
  "correctAnswer": "a",
  "explanation": "...",
  "tags": ["...", "..."]
}]

Test Series & Test Creation

POST `/api/test-series`

{ "title": "..." }

POST `/api/tests`

{ "testSeriesId": "...", "title": "...", "description": "...", "questionIds": ["..."] }

GET `/api/tests/:id`

{
  "id": "...",
  "title": "...",
  "description": "...",
  "questions": [
    {
      "id": "...",
      "text": "...",
      "options": { "a": "...", "b": "...", "c": "...", "d": "..." }
    }, ...
  ]
}

Test Attempt Workflow

POST `/api/attempts/start`

Starts a test attempt.

{ "testId": "..." }

Response:

{ "attemptId": "...", "startedAt": "..." }

GET `/api/attempts/:attemptId/questions?offset=0&limit=10`

Paginated scroll view of questions.

POST `/api/attempts/:attemptId/response`

Submit or update a response for a question.

{
  "questionId": "...",
  "selectedOption": "a",
  "markedForReview": true
}

POST `/api/attempts/:attemptId/submit`

Submits entire test.
Response:

{
  "score": 18,
  "total": 20,
  "detailedBreakdown": [
    { "questionId": "...", "correct": true, "yourAnswer": "a", "explanation": "..." }
  ]
}

Attempt History & Leaderboard

GET `/api/attempts/history`

[
  { "testTitle": "...", "score": 18, "total": 20, "submittedAt": "..." },
  ...
]

GET `/api/leaderboard`

Returns top average scores.

[
  { "user": "User1", "avgScore": 92 },
  { "user": "You", "avgScore": 85 }
]

GET `/api/user/progress`

Get performance trend.

{
  "history": [
    { "date": "2025-07-10", "score": 12 },
    { "date": "2025-07-12", "score": 18 }
  ]
}

React UI Capabilities

Auth context (register/login/logout/forgot/reset)
Dashboard for question bank management
Drag-drop or file-picker for PDF upload
Polling spinner for background extraction
Question browser per set
Create test from questions picker UI
Scrollable view with react-window for test attempt
Mark for review toggle
Submission confirmation and result view
History + leaderboard UI with charts

All user-provided requirements are now covered:
✅ Question creation
✅ Tag-based filtering
✅ PDF upload + background extraction
✅ Long polling
✅ Test & TestSeries
✅ Attempt lifecycle + scroll
✅ Mark-for-review
✅ Final score + response tracking
✅ History + Leaderboard + Progress

DEV Community: himanshu

Quizy - Technical Design & API Contract

✅ Functional Requirements (FRD) – Quizy

🔐 User Authentication & Accounts

📚 Question Bank Management

📄 Question Set Upload & Processing

🧪 Test Creation & Series

📝 Test Taking (Attempt Lifecycle)

📈 Tracking & Analytics

🏷️ Tag-based Features

🧰 Admin/Moderation (Future Scope)

🔁 System Functional Notes

Quizy - Quiz Application (API-First Design)

Stack Overview

Data Models (PostgreSQL via Prisma)

User

QuestionBank

QuestionSet

Question

TestSeries

Test

Attempt

API Contracts

Authentication

POST /api/auth/register

POST /api/auth/login

POST /api/auth/refresh

POST /api/auth/forgot

POST /api/auth/reset

Question Bank

POST /api/question-banks

GET /api/question-banks

Question Set & PDF Upload

POST /api/question-banks/:id/question-sets

GET /api/question-sets/:id/status

GET /api/question-sets/:id/questions

Test Series & Test Creation

POST /api/test-series

POST /api/tests

GET /api/tests/:id

Test Attempt Workflow

POST /api/attempts/start

GET /api/attempts/:attemptId/questions?offset=0&limit=10

POST /api/attempts/:attemptId/response

POST /api/attempts/:attemptId/submit

Attempt History & Leaderboard

GET /api/attempts/history

GET /api/leaderboard

GET /api/user/progress

React UI Capabilities

POST `/api/auth/register`

POST `/api/auth/login`

POST `/api/auth/refresh`

POST `/api/auth/forgot`

POST `/api/auth/reset`

POST `/api/question-banks`

GET `/api/question-banks`

POST `/api/question-banks/:id/question-sets`

GET `/api/question-sets/:id/status`

GET `/api/question-sets/:id/questions`

POST `/api/test-series`

POST `/api/tests`

GET `/api/tests/:id`

POST `/api/attempts/start`

GET `/api/attempts/:attemptId/questions?offset=0&limit=10`

POST `/api/attempts/:attemptId/response`

POST `/api/attempts/:attemptId/submit`

GET `/api/attempts/history`

GET `/api/leaderboard`

GET `/api/user/progress`