Project Docs

Internal documentation for the QA Learning Platform — how it is built, what it must do, and how content is structured.

Architecture

This document describes the technical architecture of the QA Learning Platform.

Monorepo Structure

qa-learning-platform/
  frontend/
  backend/
  docs/
  docker-compose.yml
  .env.example
  README.md
  AGENTS.md

The repository keeps frontend, backend, documentation, and deployment configuration together so Codex and human developers can reason about full-stack changes.

Frontend Structure

frontend/
  app/
    admin/
    courses/
    dashboard/
    final-projects/
    homework/
    lessons/
    login/
    progress/
    quiz/
    register/
  components/
    admin/
    ai/
    course/
  lib/
    api.ts
  types/
    course.ts
  styles/

Rules:

Pages live in frontend/app.
Reusable UI lives in frontend/components.
API calls live in frontend/lib/api.ts.
Shared frontend types live in frontend/types.
Student-facing pages must remain in English.
Admin workflows should be feature-complete enough for real content editing.

Backend Structure

backend/
  app/
    ai/
      providers.py
    api/
      routes/
    auth/
    core/
      config.py
    database/
      session.py
    models/
      entities.py
    schemas/
    seed/
      seed_data.py
    services/

Rules:

FastAPI app starts from backend/app/main.py.
Routes are grouped by domain.
Pydantic schemas are grouped by domain.
SQLAlchemy models are centralized in models/entities.py.
AI provider abstraction lives under app/ai.
Business logic should move to services when it becomes more than simple CRUD.

Database Structure

Main model groups:

User Models

User
UserProfile
UserProgress

Course Models

Course
Module
Lesson
LessonSlide
LessonExample
LessonInteractiveTask
Homework
HomeworkSubmission
Quiz
QuizQuestion
QuizAnswer
QuizAttempt
FinalProject
FinalProjectSubmission

AI Models

AiChatSession
AiChatMessage
AiGeneratedTask
AiGeneratedQuiz
AiHomeworkFeedback
AiUsageLog
AiSetting
AiGeneratedImage

AI Provider Abstraction

Text providers:

OpenAIProvider
OpenRouterProvider

Image provider:

OpenAIImageProvider

Rules:

Frontend never calls providers directly.
Backend chooses provider based on safe settings.
API keys are environment-only.
Runtime AI settings may override non-secret values such as provider, model, limits, temperature, and token limits.

API Structure

Base API URL:

http://localhost:8000

Main route groups:

/api/auth
/api/courses
/api/quizzes
/api/homework
/api/progress
/api/ai

Examples:

POST /api/auth/login
GET /api/courses
GET /api/courses/lessons/{lesson_id}
POST /api/quizzes/{quiz_id}/submit
POST /api/homework/{homework_id}/submit
GET /api/progress/dashboard/{user_id}
POST /api/ai/chat
POST /api/ai/images/generate

Auth Structure

Current auth:

email/password registration
email/password login
JWT access token
/api/auth/me
editable profile fields

Frontend stores demo token in local storage for MVP flows.

Security rules:

Do not trust local storage for authorization decisions.
Backend must validate JWT.
API keys must never be sent to frontend.
Production should add role checks for admin endpoints.

Admin Panel Structure

Admin workspace includes:

AI settings
AI usage
module manager
lesson manager
quiz manager
slide manager
example manager
interactive practice manager
AI image generator
homework manager
homework review
final project review
student progress
generated image history

Admin components live under:

frontend/components/admin/

Deployment Structure

Docker Compose services:

db: PostgreSQL
backend: FastAPI
frontend: Next.js

Typical command:

docker compose up --build

Backend port:

Frontend port:

Data Flow Examples

Lesson Page

Frontend calls GET /api/courses/lessons/{lesson_id}.
Backend returns lesson, slides, examples, and interactive tasks.
Frontend renders lesson content.
LessonProgressTracker marks lesson opened.
AI Assistant uses lesson ID for contextual help.

Quiz Submit

Frontend loads quiz by lesson.
Student selects answers.
Frontend posts answer IDs.
Backend calculates score.
Backend saves QuizAttempt.
Backend updates UserProgress.
Frontend shows score and wrong answer explanations.

AI Image Generation

Admin enters prompt.
Frontend posts prompt metadata to backend.
Backend enhances prompt.
Backend calls GPT Image.
Backend saves file and metadata.
Frontend previews image and can attach it to slide content.

QA Learning Platform - Business Requirements

1. Project Goal

Create an online learning platform for QA education that helps students learn Manual QA, QA Automation, and AI for QA through structured lessons, practical examples, interactive tasks, homework, quizzes, progress tracking, final projects, and mock interview preparation.

The platform should guide a beginner toward job-ready QA skills.

2. Business Problem

Beginner QA students often learn from scattered materials and lack a clear practical path. Common gaps include:

structured QA curriculum;
realistic QA artifacts;
homework with clear expected results;
knowledge checks;
mock interview preparation;
guidance on using AI in QA work;
visible progress and motivation.

3. Target Audience

Primary users:

beginner QA students;
people transitioning into IT;
junior manual QA engineers;
manual QA engineers moving toward automation;
QA specialists who want to use AI in their workflow.

Secondary users:

teachers;
mentors;
platform administrators.

4. Product Value

The platform should provide a practical learning loop:

Course -> Module -> Lesson -> Theory -> Examples -> Slides -> Practice -> Homework -> Quiz -> Progress -> Final Project -> Interview Prep

Students should understand what they have completed, what remains, which skills they have practiced, and how ready they are for final projects or interviews.

5. Core Business Functions

The platform must support three learning tracks:

Manual QA;
QA Automation;
AI for QA.

Each track should include:

courses;
modules;
lessons;
slides;
practical examples;
interactive tasks;
homework;
quizzes;
final projects;
progress tracking.

6. Learning Content Requirements

All student-facing learning content should be written in English.

Each lesson should include:

title;
short description;
learning goals;
theory explanation;
key terms;
real-world example;
step-by-step explanation;
common mistakes;
practical use case;
summary;
slides;
examples;
interactive practice;
homework;
quiz.

The platform should include practical QA artifacts such as:

checklists;
traceability matrices;
test plans;
test cases;
bug reports;
test summary reports;
AI prompts for QA tasks.

7. Mock Interview Requirements

The platform should provide a dedicated mock interview section.

The interview section should include popular QA interview questions grouped by topic:

QA Foundations;
SDLC and STLC;
Test Design;
QA Documentation;
Testing Types;
API and Web Testing;
SQL, Git, Jira, and Agile;
Automation Basics;
AI for QA.

Each interview question should include:

question;
strong answer anchor;
practice drill.

8. Student Requirements

A student should be able to:

register an account;
log in;
be redirected to the dashboard after successful login;
browse courses;
open modules and lessons;
view lesson slides;
read examples;
complete interactive practice;
submit homework;
pass quizzes;
track learning progress;
submit final projects;
prepare for interviews;
use the AI Assistant.

9. Admin Requirements

An administrator should be able to:

manage courses;
manage modules;
manage lessons;
manage slides;
add and edit examples;
create homework;
create quiz questions;
view student progress;
review homework;
review final projects;
manage AI settings;
view AI usage;
generate AI images;
attach generated images to learning content.

10. AI Assistant Requirements

The AI Assistant should help students:

explain lesson topics;
generate additional examples;
generate practice tasks;
generate extra quizzes;
check homework;
get help with automation QA.

AI requests must go through the backend. The frontend must not call OpenAI, OpenRouter, or other AI providers directly.

11. Progress Tracking Requirements

The platform should track:

opened lessons;
completed lessons;
completed quizzes;
submitted homework;
final project submissions;
certificate readiness;
gamification progress.

The dashboard should show:

current progress;
recommended next lesson;
completed lessons count;
completed quizzes count;
submitted homework count;
AI usage;
final project status.

12. Gamification Requirements

The platform should support:

XP;
levels;
ranks;
achievements;
leaderboard;
streak days.

Gamification should motivate students to complete lessons, quizzes, homework, and final projects.

13. Final Project Requirements

Each learning track should include a final project:

Manual QA Final Project;
Automation QA Final Project;
AI QA Final Project.

Final projects should validate practical readiness. Administrators should be able to review submissions and assign a status.

14. Non-Functional Requirements

The platform should:

run in a web browser;
work on desktop and mobile layouts;
support local launch with Docker Compose;
expose backend API documentation;
use PostgreSQL for persistent data;
keep API keys out of frontend code;
keep AI provider calls backend-only;
have a clear project structure;
support future course expansion.

15. Success Criteria

The project is successful when:

students can complete the full flow from registration to final project;
lessons contain theory, slides, examples, and practice;
realistic QA artifacts are available;
the mock interview section works;
dashboard and progress tracking work;
administrators can manage learning content;
AI Assistant works through the backend;
the project runs locally with Docker Compose.

QA Learning Platform - Functional Requirements

1. Purpose

This document describes functional requirements for the QA Learning Platform.

The requirements are written so they can be used as a basis for a QA project, including:

test plan;
test scenarios;
test cases;
checklists;
traceability matrix;
bug reports;
test summary report.

2. User Roles

FR-ROLE-001: Student Role

The system shall allow a student to:

register;
log in;
view courses;
open modules and lessons;
study lesson content;
view slides;
complete quizzes;
submit homework;
track progress;
submit final projects;
use AI Assistant;
use mock interview preparation.

FR-ROLE-002: Admin Role

The system shall allow an admin to:

manage courses;
manage modules;
manage lessons;
manage slides;
manage examples;
manage interactive tasks;
manage homework;
manage quizzes;
review homework;
review final projects;
view student progress;
manage AI settings;
view AI usage;
generate and attach AI images.

3. Authentication

FR-AUTH-001: Student Registration

The system shall allow a new student to create an account using:

full name;
email;
password.

Acceptance criteria:

The email must be unique.
The system must reject invalid or already registered emails.
The system must reject invalid passwords according to backend validation rules.
After successful registration, the user must be authenticated.
After successful registration, the user must be redirected to the dashboard.

FR-AUTH-002: Login

The system shall allow a registered user to log in using email and password.

Acceptance criteria:

Valid credentials must authenticate the user.
Invalid credentials must show an error message.
After successful login, the token must be saved in browser storage.
After successful login, the user must be redirected to the dashboard.

FR-AUTH-003: Logout

The system shall allow an authenticated user to log out.

Acceptance criteria:

The access token must be removed from browser storage.
User data must be removed from browser storage.
The user must no longer be treated as authenticated.

4. Course Catalog

FR-COURSE-001: View Course Catalog

The system shall display the list of available courses.

Acceptance criteria:

The course catalog must show all available course tracks.
Each course must show title, section, description, and module count.
If there are no courses, the system must show an empty state.

FR-COURSE-002: Open Course Module

The system shall allow a student to open a course module.

Acceptance criteria:

A module page must show module title and description.
A module page must show all lessons inside the module.
Lessons must be ordered by order_index.

5. Lessons

FR-LESSON-001: View Lesson

The system shall allow a student to open a lesson page.

Acceptance criteria:

The lesson page must show lesson title.
The lesson page must show short description.
The lesson page must show learning goals.
The lesson page must show theory explanation.
The lesson page must show key terms.
The lesson page must show real-world example.
The lesson page must show step-by-step explanation.
The lesson page must show common mistakes.
The lesson page must show practical use case.
The lesson page must show summary.

FR-LESSON-002: Lesson Progress Tracking

The system shall track when a student opens or completes a lesson.

Acceptance criteria:

Opening a lesson must be recorded as progress.
Completing a lesson must update progress.
Updated progress must be visible on the dashboard and progress pages.

6. Lesson Slides

FR-SLIDE-001: View Lesson Slides

The system shall display slides for each lesson.

Acceptance criteria:

The lesson page must show the Slides section.
Slides must be ordered by order_index.
Each slide must show title and body.
If a slide has an image, the image must be displayed.
Slide images must load from backend static uploads.

FR-SLIDE-002: Slide Drawer

The system shall provide a slide drawer for lesson slides.

Acceptance criteria:

A student must be able to open the slide drawer.
The drawer must show the list of slides.
The drawer must show the active slide.
The student must be able to navigate to the previous and next slide.
The drawer must support closing with the close button.
The drawer must support closing with the Escape key.

FR-SLIDE-003: Fullscreen Slide Image

The system shall allow fullscreen preview for slides with images.

Acceptance criteria:

If a slide has an image, the user must be able to open it fullscreen.
Fullscreen mode must show the image, slide title, and slide number.
Fullscreen mode must support previous and next slide navigation.
Fullscreen mode must support closing.

7. Examples

FR-EXAMPLE-001: View Lesson Examples

The system shall display practical examples for each lesson.

Acceptance criteria:

The lesson page must show an Examples section.
Each example must show title and content.
Example content must preserve line breaks.

FR-EXAMPLE-002: QA Artifact Examples

The system shall provide practical QA artifact examples.

Acceptance criteria:

The platform must include checklist examples.
The platform must include traceability matrix examples.
The platform must include test plan examples.
The platform must include test case examples.
The platform must include bug report examples.
The platform must include test summary report examples.

8. Interactive Practice

FR-PRACTICE-001: View Interactive Practice

The system shall show interactive practice tasks on the lesson page.

Acceptance criteria:

The lesson page must show task type.
The lesson page must show task prompt.
The lesson page must show expected answer guide.
The expected answer guide may be hidden inside expandable details.

9. Homework

FR-HOMEWORK-001: View Homework

The system shall allow a student to open homework for a lesson.

Acceptance criteria:

Homework page must show task description.
Homework page must show expected result.
Homework page must allow text submission.
Homework page may allow file upload if enabled.

FR-HOMEWORK-002: Submit Homework

The system shall allow a student to submit homework.

Acceptance criteria:

A student must be able to submit an answer.
Submitted homework must be saved.
Homework submission must update student progress.
Submitted homework must be available for admin review.

FR-HOMEWORK-003: Review Homework

The system shall allow an admin to review homework submissions.

Acceptance criteria:

Admin must see submitted homework.
Admin must see student answer.
Admin must be able to update homework status.

10. Quizzes

FR-QUIZ-001: View Quiz

The system shall allow a student to open a quiz for a lesson.

Acceptance criteria:

Quiz page must show quiz title.
Quiz page must show questions.
Each question must show answer options.

FR-QUIZ-002: Submit Quiz

The system shall allow a student to submit quiz answers.

Acceptance criteria:

Student must be able to select answers.
The system must calculate score.
The system must show quiz result.
Quiz completion must update progress.

FR-QUIZ-003: Admin Quiz Management

The system shall allow an admin to manage quiz questions.

Acceptance criteria:

Admin must be able to create quiz questions.
Admin must be able to update quiz questions.
Admin must be able to delete quiz questions.
Admin must be able to define correct answers.

11. Dashboard

FR-DASH-001: Student Dashboard

The system shall show a student dashboard.

Acceptance criteria:

Dashboard must show completed lessons count.
Dashboard must show opened lessons count.
Dashboard must show completed quizzes count.
Dashboard must show submitted homework count.
Dashboard must show current module.
Dashboard must show current lesson.
Dashboard must show recommended next lesson.
Dashboard must show AI usage for the current day.
Dashboard must show final project progress.

12. Progress

FR-PROGRESS-001: View Learning Progress

The system shall allow a student to view learning progress.

Acceptance criteria:

Progress page must show lesson progress.
Progress page must show quiz progress.
Progress page must show homework progress.
Progress page must show certificate readiness indicators.

FR-PROGRESS-002: Admin Student Progress

The system shall allow an admin to view student progress.

Acceptance criteria:

Admin must see student email.
Admin must see lesson title.
Admin must see opened status.
Admin must see completed status.
Admin must see quiz completion status.
Admin must see homework submission status.
Admin must see last update date.

13. Gamification

FR-GAME-001: Player Stats

The system shall show gamification stats for a student.

Acceptance criteria:

The system must show XP.
The system must show level.
The system must show rank.
The system must show next rank.
The system must show streak days.
The system must show unlocked achievements.

FR-GAME-002: Achievements

The system shall unlock achievements based on student activity.

Acceptance criteria:

Opening lessons may unlock achievements.
Completing lessons may unlock achievements.
Completing quizzes may unlock achievements.
Submitting homework may unlock achievements.
Using AI Assistant may unlock achievements.
Submitting final projects may unlock achievements.

FR-GAME-003: Leaderboard

The system shall show a leaderboard.

Acceptance criteria:

Leaderboard must show student position.
Leaderboard must show student name or email.
Leaderboard must show XP.
Leaderboard must show level.
Leaderboard must show rank.

14. Final Projects

FR-PROJECT-001: View Final Projects

The system shall allow students to view final projects.

Acceptance criteria:

Final project page must show available final projects.
Each project must show title and requirements.

FR-PROJECT-002: Submit Final Project

The system shall allow students to submit a final project.

Acceptance criteria:

Student must be able to submit project text.
Student may attach a file URL.
Submission must be saved with status.
Submission must be available for admin review.

FR-PROJECT-003: Review Final Project

The system shall allow admins to review final project submissions.

Acceptance criteria:

Admin must see submitted final projects.
Admin must be able to approve submission.
Admin must be able to mark submission as needing changes.

15. Certificate Readiness

FR-CERT-001: View Certificate Readiness

The system shall show certificate readiness based on student progress.

Acceptance criteria:

Certificate page must show required learning milestones.
Certificate page must show completed and remaining requirements.
Certificate readiness must depend on lessons, quizzes, homework, and final projects.

16. Mock Interview

FR-INTERVIEW-001: View Mock Interview Section

The system shall provide a mock interview page.

Acceptance criteria:

The page must be available from navigation.
The page must show interview topics.
The page must show the total number of topics.
The page must show the total number of questions.

FR-INTERVIEW-002: Interview Questions by Topic

The system shall group interview questions by testing topic.

Acceptance criteria:

Questions must be grouped by topic.
Each topic must show title and focus.
Each question must be expandable.
Each question must include a strong answer anchor.
Each question must include a practice drill.

Required topics:

QA Foundations;
SDLC and STLC;
Test Design;
QA Documentation;
Testing Types;
API and Web Testing;
SQL, Git, Jira, and Agile;
Automation Basics;
AI for QA.

17. AI Assistant

FR-AI-001: Open AI Assistant

The system shall allow a student to open AI Assistant from lesson pages.

Acceptance criteria:

AI Assistant button must be visible on lesson pages.
Clicking the button must open the AI Assistant panel.
Student must be able to close the panel.

FR-AI-002: Send AI Message

The system shall allow a student to send a message to AI Assistant.

Acceptance criteria:

Student must be able to enter a message.
Student must be able to submit the message.
The system must show the student message.
The system must show the AI response.
If the AI request fails, the system must show an error message.

FR-AI-003: AI Quick Actions

The system shall provide AI quick actions.

Acceptance criteria:

Student must be able to request topic explanation.
Student must be able to request more examples.
Student must be able to request a practice task.
Student must be able to request an extra quiz.
Student must be able to request homework help.
Student must be able to request automation help.

FR-AI-004: Backend-Only AI Provider Calls

The system shall send AI provider requests only from the backend.

Acceptance criteria:

Frontend must not store AI provider API keys.
Frontend must not call OpenAI or OpenRouter directly.
Backend must process AI chat requests.
Backend must enforce AI usage limits.

18. AI Image Generation

FR-IMG-001: Generate AI Image

The system shall allow admins to generate AI images for learning content.

Acceptance criteria:

Admin must be able to enter image prompt.
Admin must be able to choose target type.
Admin must be able to choose image style.
Admin must be able to choose image size.
Generated image must be saved under backend uploads.
Generated image metadata must be saved.

FR-IMG-002: Attach AI Image

The system shall allow admins to attach generated AI images to learning content.

Acceptance criteria:

Admin must be able to select generated image.
Admin must be able to attach image to lesson-related content.
Attached image must be visible in the related student-facing view when supported.

19. Admin Content Management

FR-ADMIN-001: Manage Courses

The system shall allow admin users to manage courses.

Acceptance criteria:

Admin must be able to create courses.
Admin must be able to update courses.
Admin must be able to view course list.

FR-ADMIN-002: Manage Modules

The system shall allow admin users to manage modules.

Acceptance criteria:

Admin must be able to create modules.
Admin must be able to update modules.
Admin must be able to delete modules.
Module order must be configurable.

FR-ADMIN-003: Manage Lessons

The system shall allow admin users to manage lessons.

Acceptance criteria:

Admin must be able to create lessons.
Admin must be able to update lessons.
Admin must be able to delete lessons.
Lesson order must be configurable.

FR-ADMIN-004: Manage Slides

The system shall allow admin users to manage slides.

Acceptance criteria:

Admin must be able to create slides.
Admin must be able to update slides.
Admin must be able to attach image URL to slides.
Slide order must be configurable.

FR-ADMIN-005: Manage Examples

The system shall allow admin users to manage lesson examples.

Acceptance criteria:

Admin must be able to create examples.
Admin must be able to update examples.
Examples must be connected to lessons.

FR-ADMIN-006: Manage Interactive Tasks

The system shall allow admin users to manage interactive tasks.

Acceptance criteria:

Admin must be able to create interactive tasks.
Admin must be able to update interactive tasks.
Task must include type, prompt, and expected answer.

20. Error Handling

FR-ERROR-001: API Error Handling

The system shall handle API errors gracefully.

Acceptance criteria:

If backend is unavailable, frontend must not crash.
User-facing pages must show clear fallback or error message.
Admin panels must show error messages when loading or saving fails.

FR-ERROR-002: Empty States

The system shall show empty states when data is missing.

Acceptance criteria:

Course catalog must show empty state if no courses exist.
Progress pages must show empty state if no progress exists.
Admin panels must show empty state if there are no records.

21. Security Requirements

FR-SEC-001: Token Storage

The system shall store the user access token after successful authentication.

Acceptance criteria:

Token must be saved after login.
Token must be saved after registration.
Token must be removed after logout.

FR-SEC-002: Protected User Data

The system shall require authorization for user profile operations.

Acceptance criteria:

Profile data must require a valid bearer token.
Invalid token must be rejected.
Missing token must be rejected.

FR-SEC-003: API Keys

The system shall keep provider API keys out of frontend code.

Acceptance criteria:

AI provider keys must be stored only in backend environment variables.
NEXT_PUBLIC_* variables must not contain secrets.

22. Data Requirements

FR-DATA-001: Persistent Data

The system shall persist core platform data in PostgreSQL.

Required data:

users;
user profiles;
courses;
modules;
lessons;
slides;
examples;
interactive tasks;
homework;
homework submissions;
quizzes;
quiz attempts;
progress;
final projects;
final project submissions;
AI usage logs;
AI generated images;
gamification stats;
achievements.

FR-DATA-002: Seed Data

The system shall provide seed data for local testing.

Acceptance criteria:

Seed data must create demo admin user.
Seed data must create demo student user.
Seed data must create courses.
Seed data must create modules.
Seed data must create lessons.
Seed data must create slides.
Seed data must create examples.
Seed data must create homework.
Seed data must create quizzes.
Seed data must create final projects.

23. QA Project Deliverables

Based on these requirements, a QA project should include:

requirements analysis;
test plan;
test strategy;
test scenarios;
test cases;
checklists;
traceability matrix;
bug reports;
test summary report.

Recommended traceability format:

Requirement ID | Requirement | Test Scenario | Test Case ID | Priority | Status

Recommended test case format:

Test Case ID
Requirement ID
Title
Priority
Preconditions
Test Data
Steps
Expected Result
Actual Result
Status

Glossary

FR-GLOSSARY-001: QA Glossary

The system shall provide a public glossary of core QA terms.

The glossary lists ~177 core testing terms (terms that recur across multiple lessons), each with a concise definition and a category.
Terms are served from GET /api/glossary (table glossary_terms, seeded from seed/glossary.json via app.seed.apply_glossary).
The /glossary page is reachable from the main navigation, supports search by term or definition, and groups terms alphabetically with per-term anchors.

FR-GLOSSARY-002: Lesson term links

Each lesson's "Key terms" are rendered as links to the matching glossary entry (/glossary#<slug>), so learners can open a definition from any lesson.

Test Documentation Practice

FR-TESTDOCS-001: Practice writing test cases and bug reports

The system shall let a logged-in user practise writing test documentation.

A /test-docs section offers two document types: Test Case and Bug Report, each with a type-specific structured form.
Practice runs against realistic scenarios stored as DocScenario rows (seeded set via app.seed.apply_doc_scenarios), with an on-demand "New (AI)" generator that creates a fresh scenario.
Submissions, scores and feedback are saved per-user as DocAttempt rows and shown in a history list; each attempt grants XP.

FR-TESTDOCS-002: AI review of submissions

On submit, an AI reviewer scores the document 0-100 and returns a short summary, a per-field rating (good / weak / missing), and 2-4 concrete improvements. Blank fields are flagged missing; submissions that do not match the scenario are penalised. Endpoints: GET /api/test-docs/scenarios, POST /api/test-docs/generate, POST /api/test-docs/review, GET /api/test-docs/attempts.

Course Plan

This document defines the learning structure for the Interactive QA Manual, QA Automation, and AI for QA platform.

All learner-facing course content must be written in English.

Learning Loop

Each topic follows this loop:

Topic -> Theory -> Example -> Interactive Practice -> Homework -> Quiz -> Progress.

The purpose is to help students move from concept understanding to practical QA portfolio work.

Manual QA Course Structure

Manual QA teaches software testing fundamentals, documentation, test design, API basics, SQL basics, tools, and Agile workflow.

QA Automation Course Structure

QA Automation teaches programming foundations, selectors, browser automation, test architecture, API automation, reporting, and CI/CD.

AI for QA Course Structure

AI for QA teaches responsible use of AI in test analysis, test generation, automation help, debugging, documentation, and verification.

Lesson Structure

Every lesson should include:

Title
Short description
Learning goals
Theory explanation
Key terms
Real-world example
Step-by-step explanation
Common mistakes
Practical use case
Summary
Slides
Examples
Interactive practice
Homework
Quiz
AI Assistant support

Example lesson content pattern:

Title: Bug reports
Short description: Learn how to document software defects clearly.
Learning goals: Identify useful bug report fields and explain expected vs actual results.
Theory: A bug report is a communication artifact that helps a team reproduce, prioritize, and fix a defect.
Real-world example: A checkout button does not submit an order in Safari.
Interactive practice: Analyze a weak bug report and improve it.
Homework: Write a bug report for a failed login flow.
Quiz: 10-15 questions about bug report fields and quality.

Homework Structure

Each homework item must include:

Clear task description
Expected result
Text submission field
Optional file upload placeholder
AI homework checking option
Teacher/admin review status

Good homework example:

Task: Write three test cases for a login form.
Expected result: Each test case must include preconditions, steps, expected result, and priority.

Quiz Structure

Each lesson quiz should include:

10-15 questions for full production content
Single choice questions
Multiple choice questions
True/false questions
Practical scenario questions
Score calculation
Wrong answer explanations
Retry support
Saved quiz attempt

MVP seed quizzes may start with 10 questions per lesson.

Final Projects

Manual QA Final Project

Students must:

Analyze a demo website
Create a checklist
Create test cases
Create bug reports
Create a test summary report

Automation QA Final Project

Students must:

Create Playwright tests
Test a login flow
Test form validation
Test an API endpoint
Generate a report
Explain how tests would run in CI

AI for QA Final Project

Students must:

Use AI to analyze requirements
Generate test cases with AI
Verify AI output manually
Improve AI-generated tests
Automate part of the tests
Create a final QA report

Progress Logic

Progress is tracked per user and lesson.

Tracked fields:

opened
completed
quiz_completed
homework_submitted
updated_at

Progress rules:

Opening a lesson marks it as opened.
Submitting homework marks homework as submitted.
Submitting a quiz marks quiz as completed.
A perfect quiz score can mark the lesson as completed.
Dashboard progress should calculate totals from database lessons, not hardcoded values.
Certificate readiness should require lessons, quizzes, homework, and approved final projects.

Recommended future progress additions:

Per-course progress
Per-module progress
Best quiz score
Homework approval percentage
Final project approval status

AI Assistant

This document describes the AI Assistant used in the QA Learning Platform.

The assistant is a core feature. It is not optional.

Goals

The AI Assistant helps students:

understand QA concepts in simpler language
get extra examples
practice with additional tasks
generate extra quiz questions
improve homework submissions
debug automation problems
learn responsible AI use in QA

The assistant must be friendly, beginner-friendly, and practical. It should teach students how to think, not only provide final answers.

Supported Modes

The backend supports these modes:

explain
generate_task
generate_quiz
check_homework
automation_help

The response type maps to:

explain -> explanation
generate_task -> task
generate_quiz -> quiz
check_homework -> feedback
automation_help -> code_help

Explain Mode

Purpose: explain the current lesson topic in simple terms.

Useful for:

beginner summaries
analogies
step-by-step explanations
examples
clarifying key terms

Example prompt:

Explain regression testing in simple words with one real QA example.

Expected behavior:

Use lesson context.
Keep answer concise unless the student asks for depth.
Use clear English.

Generate Task Mode

Purpose: create extra practice tasks for the current lesson.

Example prompt:

Generate 5 practice tasks for writing bug reports.

Expected behavior:

Return practical tasks students can complete.
Include realistic QA scenarios.
Avoid tasks unrelated to the current lesson.

Persistence:

Generated task responses should be saved in AiGeneratedTask.

Generate Quiz Mode

Purpose: generate extra quizzes beyond the default stored quiz.

Example prompt:

Generate a 5-question quiz about API status codes.

Preferred response format:

{
  "questions": [
    {
      "type": "single",
      "question": "Which HTTP status code means Not Found?",
      "options": ["200", "201", "404", "500"],
      "correctAnswer": "404",
      "explanation": "404 means the requested resource was not found."
    }
  ]
}

Expected behavior:

Prefer structured JSON.
Include single, multiple, true/false, and scenario questions when useful.
Include explanations.

Persistence:

Generated quiz responses should be saved in AiGeneratedQuiz.

Check Homework Mode

Purpose: help students improve homework.

Example prompt:

Check this homework and guide me without simply replacing my work.

Expected behavior:

Give feedback.
Explain what is missing.
Suggest improvements.
Avoid simply doing the full assignment for the student.

Recommended structure:

What is good:
- ...

What to improve:
- ...

Next step:
- ...

Automation Help Mode

Purpose: help with QA automation topics.

Supported topics:

XPath selectors
CSS selectors
Playwright tests
Selenium tests
Page Object Model
assertions
waits
failed test debugging
API automation

Example prompt:

Why does this Playwright locator fail, and how can I make it stable?

Expected behavior:

Explain the cause.
Provide clean code examples when needed.
Prefer stable locators.
Mention verification steps.

Backend Endpoint Structure

Endpoint:

POST /api/ai/chat

Request:

{
  "message": "Explain this topic",
  "lessonId": "1",
  "mode": "explain"
}

Response:

{
  "answer": "Regression testing checks that existing features still work after changes.",
  "type": "explanation"
}

Backend flow:

Validate request.
Check daily usage limit.
Load lesson context.
Build system/user prompt.
Select provider.
Call OpenAI or OpenRouter.
Save chat session and messages.
Save generated task/quiz artifact when relevant.
Save usage log.
Return response.

Frontend UI Behavior

The lesson page includes a floating AI Assistant button.

The assistant sidebar should provide:

message history
quick actions
mode selector
loading state
error state
copy answer button
clear chat button
structured quiz rendering when JSON is returned

Quick actions:

Explain this topic
Give me more examples
Generate practice task
Generate extra quiz
Check my homework
Help with automation

Database Models

AI chat and usage models:

AiChatSession
AiChatMessage
AiGeneratedTask
AiGeneratedQuiz
AiHomeworkFeedback
AiUsageLog

Important fields:

AiChatSession:
- user_id
- lesson_id
- created_at

AiChatMessage:
- session_id
- role
- content
- created_at

AiUsageLog:
- user_id
- lesson_id
- mode
- provider
- model
- request_type
- created_at

Usage Limits

Text AI usage is limited by:

AI_DAILY_LIMIT_PER_USER=50

Image usage is limited separately:

AI_DAILY_IMAGE_LIMIT_PER_USER=10
AI_DAILY_IMAGE_LIMIT_ADMIN=100

When a limit is reached, the backend should return a clear 429 error.

Safety Rules

Never expose API keys to frontend.
All AI requests must go through backend.
Do not ask the model to reveal secrets.
Do not store API keys in database unless encrypted and intentionally designed later.
For homework, guide students instead of replacing their work.
For generated tests, remind students to verify AI output.
Avoid very long answers unless requested.
Keep assistant output in English.

Seed Data

This document explains how seed data is structured for the QA Learning Platform.

Seed data must be written in English.

Seed Script

Seed entrypoint:

backend/app/seed/seed_data.py

Run with Docker:

docker compose exec backend python -m app.seed.seed_data

Run locally:

cd backend
python -m app.seed.seed_data

Seeded Users

Demo users:

[email protected] / Password123
[email protected] / Password123

Rules:

Use safe demo credentials only.
Do not seed real personal data.
Do not seed real API keys.

Course Structure

Seed creates three course sections:

Manual QA
QA Automation
AI for QA

Each course has:

title
section key
description
at least one module
MVP lessons
final project

Module Structure

Each seeded course starts with a foundation module.

Example:

Course: Manual QA
Module: Manual QA Foundations
Description: Learn software testing fundamentals, test design, documentation, API basics, SQL, Git, Jira, and Agile.

Future seed expansion should add multiple modules per course, such as:

Fundamentals
Documentation
Test Design
API and SQL
Tools and Agile
Final Project

Lesson Structure

Each seeded lesson includes:

title
short description
learning goals
theory
key terms
real-world example
step-by-step explanation
common mistakes
practical use case
summary
order index

Current helper:

lesson_payload(title, description)

This helper creates a complete lesson content block from a title and course description.

Slides Structure

Each MVP lesson is seeded with 5 slides.

Fields:

lesson ID
title
body
order index
image URL

Example:

Title: Bug reports: Slide 1
Body: Key point 1: apply Bug reports through examples and practice.

Production content should expand slides to 5-10 per lesson with clearer learning steps.

Slide Asset Import

The repository can use exported PNG slide decks from docs/slides as lesson visuals.

Expected asset flow:

Extract each zip deck into backend/uploads/course-slides/<deck-slug>/.
Run the import script:

cd backend
python -m app.seed.import_slide_assets

With Docker Compose:

docker compose exec backend python -m app.seed.import_slide_assets

The script updates LessonSlide.image_url for matching seeded lessons. It only updates seed-style slides whose titles follow this pattern:

<Lesson title>: Slide <number>

This avoids overwriting custom admin-created slides.

Homework Structure

Each lesson has one homework item.

Fields:

lesson ID
task description
expected result
allow file upload

Example:

Task: Create a practical QA artifact for Bug reports.
Expected result: A concise, structured answer with expected results and evidence.

Quiz Structure

Each lesson has one quiz.

MVP seed:

10 questions per lesson
3 answer options per question
1 correct answer
explanation for wrong answers

Fields:

quiz title
question text
question type
explanation
answer text
is correct

Production quizzes should include:

single choice
multiple choice
true/false
scenario questions

Examples Structure

Each lesson includes at least one example.

Fields:

lesson ID
title
content

Example:

Title: Real QA example
Content: A team releases a checkout page. QA checks critical flows, documents issues, and helps the team understand release risk.

Interactive Task Structure

Each lesson includes one interactive task.

Fields:

lesson ID
task type
prompt
expected answer

Example:

Task type: analysis
Prompt: Review a short requirement and identify one testing risk related to Bug reports.
Expected answer: A clear risk with a matching test idea.

Final Projects

Seed creates one final project for each course:

Manual QA Final Project

Requirements:

Analyze a demo website, create checklist, test cases, bug reports, and a test summary report.

QA Automation Final Project

Requirements:

Create Playwright tests for login, form validation, API endpoints, reports, and GitHub Actions.

AI for QA Final Project

Requirements:

Use AI to analyze requirements, generate tests, verify output, improve tests, and create a QA report.

Seeded Course Catalog

The main seed script creates the full topic catalog from the project prompt. Each seeded lesson receives the complete learning flow structure: theory, 5 slides, 1 practical example, 1 interactive task, 1 homework task, and 1 quiz with 10 questions.

Manual QA seeds 47 topics across these modules:

QA Foundations.
Testing Types.
QA Documentation.
Test Design Techniques.
Technical Skills for Manual QA.

QA Automation seeds 40 topics across these modules:

Programming Foundations.
Web and Selector Foundations.
Browser Automation.
Automation Architecture.
Reports, CI, and Scaling.

AI for QA seeds 24 topics across these modules:

AI Foundations for QA.
AI for Manual QA.
AI for Technical QA.
AI QA Workflow.

For very early development, teams may temporarily seed only the first few lessons from each course, but the main seed script should stay aligned with the full course catalog.

Seed Data Expansion Rules

When adding seed content:

Keep all content in English.
Make lessons practical and beginner-friendly.
Include realistic QA examples.
Include evidence-based tasks.
Include useful quiz explanations.
Avoid vague filler content.
Keep seed script idempotent where practical.
Do not delete user-generated data during normal seed runs unless explicitly intended.