WEB QUIZ ENGINE — PYTHON + FLASK OOP APPLICATION

1. Abstract / Summary

Small-scale and collegiate web-based assessment systems are frequently built as monolithic scripts in which HTTP routing, authorization checks, and grading logic are tightly interleaved, and in which access control relies on a single hardcoded boolean flag such as is_admin. This design is difficult to test, difficult to extend with new roles or permissions, and prone to two concrete failure modes: privilege leaks (a user reaching an endpoint they should not) and orphaned data (a quiz left half-created after a database error). The Web Quiz Engine addresses both problems directly. It re-engineers the assessment workflow around a strict five-layer architecture — presentation, routing and guards, business services, repositories, and persistence — so that authorization, grading, and data-access concerns are never mixed in the same function. Access control is implemented as a normalized five-table Role-Based Access Control (RBAC) schema (users, roles, permissions, and two bridge tables) enforced through a custom @require_permission decorator, replacing static role columns with dynamic, database-driven permission checks. Multi-table quiz creation (quiz → questions → options) is wrapped in an explicit MySQL/InnoDB transaction with manual rollback, guaranteeing that a failure at any step leaves zero orphaned rows. Assessment timing is verified on the server using session timestamps rather than trusting the client's JavaScript countdown alone, closing a common tampering vector. The system is implemented in Python (Flask) with a MySQL backend and a lightweight vanilla-JavaScript front end, and its domain logic is expressed as typed Python dataclasses (User, Quiz, Question, Submission) to keep business rules independent of any web framework or SQL driver. The expected output is a working three-role (Admin, Teacher, Student) quiz platform, a written design and evaluation report, and an automated test suite; at the time of writing, 36 unit, integration, and end-to-end tests pass in just over one second, covering domain scoring rules, RBAC enforcement across all permission tokens, and full user-facing flows such as timed quiz-taking, teacher grading overrides, and CSV export of class results.

2. Problem Statement

Conventional collegiate assessment web applications exhibit four recurring architectural weaknesses that this project sets out to solve:

• Coupled code organization: routing, SQL, business rules, and UI markup are combined in a single monolithic script, making the system hard to maintain and impossible to unit-test in isolation.
• Rigid, unsafe access control: a hardcoded is_admin flag or a single static role_id column cannot represent a user with multiple roles, and any new permission requires a schema and code change — increasing the risk of privilege leaks.
• Non-atomic multi-table writes: creating a quiz means inserting a parent row and many child rows (questions, then options); without a transaction wrapper, a failure partway through leaves orphaned, inconsistent data.
• Client-trusted timing: when an assessment timer runs only in browser JavaScript, a student can tamper with it (or the local system clock) to gain unlimited time, undermining the fairness of the assessment.

These four gaps — maintainability, access-control integrity, data integrity, and assessment fairness — define the concrete problem this project engineers a solution for.

3. Objectives

General Objective:
To design and implement a secure, maintainable, layered web-based quiz assessment engine that enforces reliable role-based access control and guarantees data integrity throughout quiz authoring, delivery, and grading.

Specific Objectives:

1. To design a five-tier decoupled architecture (presentation, routing/guards, business services, repositories, persistence) that separates HTTP handling from business rules and data access.
2. To implement a normalized five-table RBAC schema (users, roles, permissions, user_roles, role_permissions) that supports multiple roles per user without requiring schema changes.
3. To enforce atomic, transactional multi-table inserts for quiz creation so that any mid-operation failure rolls back cleanly and leaves no orphaned records.
4. To build a server-verified timed assessment mechanism that cannot be bypassed by client-side JavaScript or system-clock tampering.
5. To validate the system through automated unit, integration, and end-to-end tests covering domain logic, RBAC enforcement, and complete user flows for all three roles.

4. Research / Development Questions

1. How should a Flask application be layered so that grading and business rules remain fully unit-testable without a live database connection?
2. What relational schema allows a user to hold multiple roles, and new permissions to be added, without altering the users table or existing application code?
3. Which MySQL/InnoDB transaction strategy reliably prevents orphaned question or option rows when a multi-table quiz-creation operation fails partway through?
4. How can an assessment timer be enforced so it cannot be defeated by modifying client-side JavaScript or the local system clock?
5. What combination of unit, integration, and end-to-end tests provides sufficient confidence that RBAC rules and grading logic behave correctly across the Admin, Teacher, and Student roles?

5. Scope and Limitation

In Scope:

• Three user types governed by a dynamic RBAC permission model: Admin, Teacher, Student.
• Core features: quiz/question/option CRUD, timed quiz-taking, automatic grading, manual score/feedback override, and CSV export of class results.
• Core technology stack: Python, Flask, MySQL (InnoDB), vanilla JavaScript, and Jinja2 templates.

Out of Scope / Limitations:

• Third-party OAuth or social-login authentication.
• Outbound email/SMTP notifications (e.g., password-reset emails).
• Real-time video proctoring (WebRTC) during assessments.
• Native mobile applications — the system is browser-based only.

Assumptions:

• Users access the system over a trusted network and browser session.
• Class/enrollment data is seeded and managed by an Admin rather than synchronized from an external student information system.

6. Target Users and Stakeholders

• Admin: Full-privilege system operator; bypasses all permission checks. Handles user management, role assignment, account deactivation.
• Teacher: Authors and manages assessments for their own classes. Handles quiz create/edit/delete, grading overrides, CSV report export.
• Student: Assessment-taker. Browses available quizzes, attempts timed assessments, views results and feedback.
• Course Supervisor (indirect stakeholder): Faculty overseeing the course. Relies on exported CSV reports for grade records and course evaluation.

7. Proposed System Features

• Authentication & session management: login and a session hydrated with the user's roles and permissions.
• Authorization: a reusable @require_permission decorator guarding every route by permission token, with an Admin-role bypass.
• Quiz module (CRUD): create, edit, and delete quizzes, questions, and options, with structural validation (at least two options and exactly one correct answer per question).
• Assessment-taking module: floating countdown timer with server-verified start time and automatic submission on expiry.
• Grading module: automatic scoring against a configurable pass percentage, plus manual teacher override and qualitative feedback.
• Reporting module: CSV export of cohort responses for Admin/Teacher use.
• User management module (Admin only): create and deactivate accounts, assign or revoke roles.

8. OOP Design Plan

Domain Classes (typed dataclasses):

• User — id, username, email, roles: List[str], permissions: List[str]; methods has_role(name), has_permission(token).
• Quiz — title, time_limit_minutes, pass_percentage, questions: List[Question]; computed property max_possible_score.
• Question / Option — question text, point value, and a list of options, with structural rules enforced (≥2 options, exactly 1 correct).
• Submission — student_id, quiz_id, total_score, max_score, passed: bool, feedback, submitted_at, duration_elapsed.

Service Classes:

• AuthService — authenticates users and hydrates the session with roles/permissions.
• QuizService — validates quiz/question/option structure before persistence.
• GradingService — computes scores and pass/fail outcomes, fully isolated from SQL and HTTP concerns.

Repository Classes:

• UserRepository, QuizRepository, SubmissionRepository — encapsulate all parameterized SQL and atomic transactions, hiding persistence details from the service layer.

Relationships:
Flask blueprints (routing) depend only on business services; services depend on repositories through composition; repositories depend on the MySQL connection. No layer skips over the one beneath it, which enforces the Single Responsibility Principle and allows GradingService and other business rules to be unit-tested entirely in memory, without a live database connection.

9. System Architecture

The system follows a strict five-tier, one-directional dependency flow:

1. Presentation — Jinja2 templates, vanilla JavaScript, floating countdown timer, card-based quiz layout.
2. Routing & Guards — Flask Blueprints (web_bp, auth_bp, quiz_bp) with @require_permission route guards.
3. Business Services — AuthService, QuizService, GradingService — zero direct SQL.
4. Repositories — UserRepository, QuizRepository, SubmissionRepository — parameterized SQL, atomic transactions.
5. Persistence — MySQL (InnoDB) — five-table RBAC schema plus assessment tables, foreign keys with CASCADE.

Flow: Browser → Flask routes/controllers → Services → Repositories → MySQL

10. Database Plan

Main Tables:

• users — id, username, email, password_hash, is_active — Account records; passwords stored only as hashes.
• roles — id, name, description — Named roles (Admin, Teacher, Student).
• permissions — id, name, description — Atomic permission tokens (e.g., quiz:create, quiz:view).
• user_roles — user_id (FK), role_id (FK) — Bridge table: many-to-many users↔roles.
• role_permissions — role_id (FK), permission_id (FK) — Bridge table: many-to-many roles↔permissions.
• quizzes — id, title, time_limit_minutes, pass_percentage, created_by (FK) — Quiz parent record.
• questions — id, quiz_id (FK), text, points — Child of quizzes; cascades on delete.
• question_options — id, question_id (FK), text, is_correct — Child of questions; cascades on delete.
• submissions — id, student_id (FK), quiz_id (FK), total_score, max_score, passed, feedback, submitted_at — One attempt record per student per quiz.

Relationships and Constraints (ERD Summary):

• Many-to-many: users ↔ roles via user_roles; roles ↔ permissions via role_permissions.
• One-to-many: quizzes → questions → question_options; quizzes and students → submissions.
• Foreign keys on questions, question_options, and submission records are configured with ON DELETE CASCADE, so deleting a quiz automatically removes its dependent rows without orphaning data.
• The schema is normalized to Third Normal Form (3NF): no repeating groups, and role/permission membership is never encoded as a static column on users.

11. Methodology and Timeline

The project follows an iterative, sprint-based R&D workflow: each week produces a working, testable increment rather than deferring integration to the end of the term.

Weekly Sprint Plan:

• Week 1: Requirements gathering; ERD design; RBAC schema design.
• Week 2: Repository layer implementation; database seeding script (Admin/Teacher/Student personas).
• Week 3: Domain dataclasses (User, Quiz, Question, Submission); AuthService and QuizService.
• Week 4: GradingService; Flask blueprints/routes; @require_permission decorator.
• Week 5: Front end (Jinja2 templates, countdown-timer JS, CSV export); integration testing.
• Week 6: End-to-end testing, bug-fixing, defense preparation, and report writing.

Testing Approach:
Verification uses Python's standard unittest framework across three layers: domain/scoring unit tests, RBAC/security tests, and live end-to-end flow tests. At the time of writing, the full suite of 36 tests (14 domain, 16 RBAC/security, 6 end-to-end) passes with zero failures in 1.013 seconds.

12. Expected Results

• Working software: a Flask + MySQL Web Quiz Engine supporting complete Admin, Teacher, and Student flows.
• Written report: this document, covering design rationale, architecture, and evaluation.
• Live demonstration: student examination attempt with timer and auto-submission; teacher grading override; CSV export of cohort results.
• Testing evidence: 36 of 36 automated tests passing in 1.013 seconds (14 domain, 16 RBAC/security, 6 end-to-end).
• Screenshots: to be captured during the final defense — login, quiz authoring, a timed student attempt, and the CSV export flow.

13. Risk and Ethics

• Data privacy: Student scores and feedback are personal academic data. Mitigation: data is stored only in the project's MySQL instance; passwords are stored as hashes, never plaintext.
• Privilege escalation: A user could attempt to reach an endpoint above their role. Mitigation: @require_permission decorator checks dynamic session tokens against database state on every request.
• SQL injection: Unsanitized input could manipulate query syntax. Mitigation: 100% parameterized queries; zero raw string concatenation in repository classes.
• Group / workload risk: Uneven task distribution between two members. Mitigation: weekly sprint check-ins with clearly owned modules (backend/RBAC vs. frontend/testing).
• Time risk: Integration and testing time is often underestimated. Mitigation: Week 6 is reserved exclusively for end-to-end testing and defense preparation.

14. References

• Flask official documentation — https://flask.palletsprojects.com/
• MySQL / InnoDB official documentation — https://dev.mysql.com/doc/
• Python unittest standard library documentation — https://docs.python.org/3/library/unittest.html
• Course lecture materials, Advanced Object-Oriented Programming (supervised by Sek Socheat).
• General secure-coding references on SQL injection and privilege-escalation prevention (e.g., OWASP guidance).
• https://github.com/HayRavanmonyvan/Quiz_Engine