TestGenerator

Project Report: Backend API for Quiz MVP

This document outlines the final state of the FastAPI backend. We successfully pivoted from the initial "Question Bank" concept to a simpler, more direct "Quiz-Centric" model. The backend is now complete and fully functional, supporting the entire workflow for both Admins and Students.

---

Phase 1: Database Schema Overhaul

The first phase involved completely replacing the old 6-table database schema with a new, more efficient 5-table schema.

1. New Database Models (app/models/)

We created a new 5-table model that is simpler and better for analytics:

• app/models/user.py: (Unchanged)

  • Table: users
  • Purpose: Stores user accounts, hashed passwords, and roles (admin, teacher, student). This is the foundation for our authentication.

• app/models/quiz.py: (New File)

  • Table: quizzes
  • Purpose: Stores the "parent" quiz (e.g., "Physics Quiz 1"). It is linked directly to the users table to track who created it.

• app/models/question.py: (Modified)

  • Table: questions
  • Purpose: Stores a single question. It now has a quiz_id foreign key, meaning every question belongs directly to one quiz. This was the most important change.

• app/models/quiz_assignment.py: (New File)

  • Table: quiz_assignments
  • Purpose: This is the linking table that tracks which student_id is assigned to which quiz_id. We also added score (Float) and submitted_at (Timestamp) columns to store the student's final results.

• app/models/response.py: (New File)

  • Table: responses
  • Purpose: Stores a student's individual answer to a single question. This provides excellent data for analytics and makes grading simple.

2. Database Migration (Alembic)

To apply this new schema to our PostgreSQL database:

1. Manual Database Reset: We manually reset the nta_test database to clear the old, conflicting Alembic history. We ran the SQL commands DROP SCHEMA public CASCADE; and CREATE SCHEMA public; directly in psql.
2. First Migration: We ran alembic revision --autogenerate -m "..." to create a new migration script that built the 5 new tables. We applied this with alembic upgrade head.
3. Second Migration: After adding the score and submitted_at columns to the quiz_assignments model, we ran alembic revision --autogenerate ... and alembic upgrade head a second time to apply this change.

3. Module Structure (__init__.py)

To ensure our new models and schemas could be imported correctly by other parts of the app, we created two new files:

• app/models/__init__.py: This file imports all 5 of our SQLAlchemy models (User, Quiz, Question, etc.) and makes them available to the application.
• app/schemas/__init__.py: This file does the same for all our Pydantic schemas.

This structure fixed all AttributeError problems and is now stable.

---

Phase 2: Backend API (FastAPI) Implementation

With the database in place, we built the API endpoints. We created one new router (quiz.router) to hold all the new logic, which we then included in app/main.py.

All endpoints that perform "create" or "view results" actions are protected and require an Admin/Teacher token. All endpoints for "taking" a quiz require a Student token. This security is handled by the existing get_current_user dependency from app/routers/auth.py.

1. Admin Workflow Endpoints (in app/routers/quiz.py)

• POST /quizzes/

  • Purpose: Creates a new, empty quiz.
  • Security: Admin/Teacher only.
  • Body: { "title": "New Quiz Title" }
  • Returns: The newly created quiz object.

• POST /quizzes/{quiz_id}/questions

  • Purpose: Adds a new question (with options, answer, and marks) to a specific quiz.
  • Security: Admin/Teacher only, and they must be the owner of the quiz.
  • Body: { "text": "...", "options_json": {...}, "correct_answer": "A", "marks": 5 }
  • Returns: The newly created question object.

• POST /quizzes/{quiz_id}/assign

  • Purpose: Assigns a quiz to a specific student.
  • Security: Admin/Teacher only, and they must be the owner of the quiz.
  • Body: { "student_id": 2 }
  • Returns: The new quiz assignment object.

• GET /quizzes/{quiz_id}/results

  • Purpose: Gets a list of all students assigned to a quiz and their final results (score, status, etc.).
  • Security: Admin/Teacher only, and they must be the owner of the quiz.
  • Returns: A list of assignment objects, each with nested student information.

2. Student Workflow Endpoints (in app/routers/quiz.py)

• GET /quizzes/assigned/me

  • Purpose: Gets the logged-in student's "to-do list" of all quizzes they have been assigned.
  • Security: Student only.
  • Returns: A list of assignment objects, each with nested quiz information (like the quiz title).

• GET /quizzes/assigned/{assignment_id}

  • Purpose: Fetches the full quiz details (title and all questions) for a specific assignment.
  • Security: Student only, and they must be the one the quiz was assigned to.
  • Returns: The full quiz object, with a list of its questions. The correct_answer field is omitted for security.

• POST /quizzes/assigned/{assignment_id}/submit

  • Purpose: The final step. The student submits their answers. The backend grades the submission, saves every response, calculates the final score, and marks the assignment as "completed".
  • Security: Student only, and they must be the one the quiz was assigned to.
  • Body: { "answers": [ { "question_id": 1, "selected_answer": "A" }, ... ] }
  • Returns: A final result object with the total score achieved.

• Bug Fix: We also fixed a bug in this endpoint, changing datetime.utcnow() to datetime.now(timezone.utc) to ensure the submitted_at timestamp saves correctly to the database.

---

Current Status

The backend is 100% complete and tested. The API fully supports the entire MVP workflow. Ready to begin Phase 3: Build Frontend (React).