EduTrack Online — Frontend Build Order (Phase 1: SiteOwner)

Overview

Build these pages in order. Each page depends on the previous one.

Page 1: Login Page

APIs to use (from API_PUBLIC.md):

Flow:

1. User enters username + password → POST /accounts/login/
2. If 200 → store {role, name} in React state, redirect to Teachers Page (if role=siteowner)
3. If 401 → show error message
4. "Forgot Password?" link → step-by-step: email → OTP → new password

Required: Login form, Forgot Password modal/flow.

Page 2: Student Register Page (Public)

APIs to use (from API_PUBLIC.md):

3-Step Registration Flow:

Step 1:  POST /verify-email/request/ { email }
         → OTP sent to email

Step 2:  POST /verify-email/confirm/ { email, otp }
         → Returns { verified, email, verification_token }
         → Save verification_token in React state

Step 3:  POST /accounts/student/register/ { verification_token, gmail, ...all fields }
         → Server validates token matches gmail
         → Creates student if valid

Step 3 form fields:

• verification_token (hidden field — from Step 2 response)
• gmail (must match the email verified in Step 2)
• username (unique)
• password + password_confirm
• name_ar (Arabic name)
• name_en (English name)
• phone_number (Egyptian format: 010/011/012/015 + 8 digits)
• father_number, mother_number (parent phones)
• school_type (select from dropdown)
• grade (select from dropdown)
• division (select from dropdown, filters by school_type + grade)
• school_name (text input)
• birth_date (date picker)
• gender (male/female)
• governorate (select from dropdown)
• area (select from dropdown, filters by governorate)

Dropdown data: Fetch from Settings endpoints (see Page 6).

Business rules:

• Email must be verified before registration. The gmail in Step 3 must match the email verified in Step 2.
• verification_token is single-use and expires in 30 minutes.
• Division must belong to the selected school_type AND grade
• Area must belong to the selected governorate
• Student phone cannot match father's or mother's phone
• password_confirm must match password

Page 3: Teachers Page (SiteOwner Dashboard)

This is the main landing page after login. Shows all teachers as cards.

APIs to use (from API_SITEOWNER.md):

Teacher Card shows:

• Name (from name)
• Subject (from subject_name)
• Grades (from grade_names — array of strings)
• Course count (from courses_count)
• Student count (from students_count)
• Active/Inactive status badge (from is_active)
• "View Courses" button → navigates to Teacher Courses Page
• "Edit" button → opens edit modal/inline form

Teacher List Filters:

• Search by name, phone, gmail, username
• Filter by is_active
• Pagination (default 50 per page, ?all=true for all)

Teacher Create Form fields:

• username, password
• name, phone, secondary_phone, gmail
• gender (male/female — required)
• subject (ID from subjects list)
• grades (array of grade IDs — filtered by selected subject)
• is_active (checkbox, default true)
• biography, facebook (optional)

Grade filtering logic: The GET /accounts/subjects/ response includes grade_ids for each subject. When the user selects a subject, filter the grades multi-select to only show grades whose IDs are in subject.grade_ids:

const subject = subjects.find(s => s.id === selectedSubjectId);
const validGrades = allGrades.filter(g => subject.grade_ids.includes(g.id));

If no subject is selected, disable the grades field with "Select a subject first".

Backend validation: If a grade outside the subject's range is submitted, the API returns 400 with {"grades": ["Subject 'Math' is not available for grade '1st Secondary'."]}.

Success response: Returns full teacher profile with ID. Use this to navigate to the new teacher's detail.

Page 4: Teacher Detail Page (View/Edit Teacher)

Clicking on a teacher card or the edit button from the Teachers Page.

APIs to use:

Teacher Detail sections:

1. Profile Info — name, phone, gmail, subjects, grades, active status, bunny_collection_id. Editable.
2. Bunny Collection — shows current bunny_collection_id (if assigned). Button to assign a collection: PATCH /accounts/teachers/<id>/ with { "bunny_collection_id": "..." }. Or create one via POST /accounts/teachers/<id>/create-collection/.
3. Assistants List — read-only table showing assigned assistants (name, phone, gmail, is_active). Note: assistants are created later by the teacher themselves.
4. Create Course Button → opens a form to create a course for this teacher.

Course Create Form (inline):

• name (text — will be validated as unique per teacher+grade)
• grade (select from dropdown — teacher must teach this grade)
• subject (select from dropdown — required; teacher must teach this subject, and the subject must be available for the selected grade)
• description (textarea, optional)
• is_active (checkbox, default true)

Success: After creating a course, the page should show a success message and optionally navigate to the Teacher Courses Page.

Page 5: Teacher Courses Page

List all courses for a specific teacher. Accessed via "View Courses" button on teacher card.

APIs to use:

Course Card shows:

• Course name
• Grade name
• Is Active badge
• Created date
• Topic count (from topic_count in response)
• Total lectures count (from total_lectures in response)
• "Edit" button → opens edit modal
• "Delete" button → only if course is empty (no enrollments)

Course Edit Form:

• name, subject, description, is_active (all editable)
• Cannot change: teacher, grade (these are locked after creation)

Course Delete rules:

• Can only delete if no enrolled students, no topics, no lectures, no materials
• DELETE returns 400 if students are enrolled
• Return a confirmation dialog before deleting

Page 6: Students Page (SiteOwner)

Manage all student registrations. Approve/decline/suspend students. View full profile with enrollments, per-course balances, and transaction history per course.

APIs to use:

Student List Filters:

• Search by name, student_code, phone, gmail
• Filter by status (verified/pending/declined/suspended)
• Filter by grade, school_type
• Sort by created_at, name, student_code
• Pagination (default 50)

Student Table columns:

• Student Code, Name (en), Grade, Phone, Gmail, Status badge, Created date, Actions

Student Detail view (3 sections):

Section 1 — Profile Info:

• Full profile info (name_ar, name_en, phone, father/mother numbers, school info, gmail, birth_date, gender, governorate, area, etc.)
• enrollments[] array shows all courses the student is enrolled in with per-course balance, teacher name, status, enrollment date.
• Status history timeline from status_history field.

Section 2 — Status Management:

• Status change buttons (with reason field):

  • "Decline" → PATCH {status: "declined", is_active: false, reason: "..."} — reason required
  • "Suspend (Temporary)" → PATCH {status: "suspended_temporary", is_active: false, reason: "..."} — reason required
  • "Suspend (Permanent)" → PATCH {status: "suspended_permanent", is_active: false, reason: "..."} — reason required
  • "Verify/Reactivate" → PATCH {status: "verified", is_active: true, reason: "..."} — reason optional

• Status transition rules:

  • pending → only "Verify" or "Decline"
  • verified → only "Suspend" (cannot decline or set to pending)
  • declined → only "Verify" (cannot suspend)
  • suspended → only "Verify" (reactivate)

• Profile edit rules (student self-service):

  • verified → Cannot edit
  • pending → Cannot edit
  • declined → Can edit — after saving, status resets to pending
  • suspended_temporary → Cannot edit
  • suspended_permanent → Blocked from login

• Login behavior by status:

  • pending → receives {status: "pending"} — show "pending approval" page
  • verified → Normal login
  • declined → receives {status: "declined"} — show reason + prompt to edit profile
  • suspended_temporary → receives {status: "suspended_temporary"} — show reason
  • suspended_permanent → Blocked — 401 "Your account has been permanently suspended."

Section 3 — Transaction History (per course):

• SiteOwner MUST select a course first (from the enrollments table) before viewing transactions
• Once a course is selected: GET /payments/transactions/?student=<id>&course=<id>
• Shows full ledger: Date & Time | Type | Amount | Balance Before → After | Performed By | Code
• Filters: ?start_date=YYYY-MM-DD, ?end_date=YYYY-MM-DD, ?code=ABC123, ?transaction_type=code_redeemed|lecture_purchase
• Pagination: 25 per page (?page_size=25)

Default view: Show pending students first (sort by most recent).

Page 7: Settings Page (Read-Only Reference)

Display all reference data for preview. No CRUD operations.

APIs to use (from API_PUBLIC.md):

Note: All these endpoints support ?all=true to bypass pagination and get complete lists for dropdowns.

Static Files Needed

No static files are served by the backend. The frontend should handle all assets (images, icons, logos) on its own.

Auth Flow Summary

1. POST /accounts/login/ with {username, password}
2. Server sets httpOnly cookies: access_token (30min), refresh_token (7d)
3. Server returns JSON: {role: "siteowner", name: "Admin", is_active: true}
4. Frontend stores {role, name} in React context/state
5. All subsequent requests automatically send cookies (browser handles this)
6. When access_token expires → POST /accounts/token/refresh/ (reads refresh cookie)
7. POST /accounts/logout/ to clear cookies

Note: Since cookies are httpOnly, the frontend CANNOT read the JWT. Session restoration works via GET /accounts/me/ which reads the cookie and returns {role, name, is_active}.

Error Handling

All API errors follow this pattern:

{"error": "Human-readable error message"}

HTTP Status codes:

• 200 — Success
• 201 — Created
• 400 — Bad request (validation error)
• 401 — Not authenticated or invalid credentials
• 403 — Not authorized (wrong role)
• 404 — Not found
• 500 — Server error

Public (SEO) Endpoints — Landing / Teacher Listing / Subject Catalog Pages

Anonymous browsing is served by dedicated public endpoints — GET /courses/ and GET /courses/<id>/ now require authentication in all cases (even with ?teacher=), so the public pages must use these:

Rules for the public pages: hide any prices/lecture counts behind login; the "teacher → their courses" drill-down on the public teacher page uses GET /courses/public/?teacher=<id>; a logged-in student's version of the same pages uses the authenticated endpoints (/courses/, /courses/by-subject/<id>/, /courses/<id>/preview/), which are eligibility-filtered and include eligibility.

Phase 2: Teacher & Assistant Pages

Build these in order after Phase 1 is complete.

IMPORTANT: All pages in Phase 2 apply to both Teacher and Assistant roles unless noted. The only exception is the Assistants management page — assistants can view coworkers but cannot create/delete.

Dashboards (Course Dashboard, Teacher Dashboard) are built last — after all features exist.

Page 1: My Courses Page (Entry Point)

Teacher logs in → POST /accounts/login/ → JWT cookies set → GET /accounts/me/ → redirects to My Courses.

Page layout: Grid of course cards, each showing:

• Course name, grade, subject, cover picture
• Topic count, enrolled/pending/rejected counts
• Click card → navigate to Content Management

Page 2: Content Management (Topics → Lectures → Videos)

Purpose: The core page where teachers build their course content hierarchy. Teacher spends most time here.

Navigation: Select course → Topics list → Click topic → Lectures list → Click lecture → Lecture Detail

Page layout (left-to-right hierarchy):

Course: Chemistry 3rd Secondary
┌────────────────────────────────────────────────┐
│  Unit 1: Chemical Reactions          [+ Topic] │
│  ├── Lecture 1: Intro               [3 videos] │
│  ├── Lecture 2: Balancing           [2 videos] │
│  └── + Add Lecture                             │
│                                                │
│  Unit 2: Organic Chemistry                     │
│  ├── Lecture 3: Hydrocarbons        [0 videos] │
│  └── + Add Lecture                             │
└────────────────────────────────────────────────┘

Topic CRUD:

Lecture CRUD:

Click a lecture → Lecture Detail page with sub-tabs:

← Back to Content

Lecture: Intro to Chemical Reactions
Price: 50 EGP | Discount: 10 EGP | Available: 30 days

[ Videos ] [ Purchases ] [ Homework ] [ Quiz ] [ Materials ] [ Prerequisites ]

Each sub-tab is built when its corresponding page below is completed.

Video tab (built here):

Bunny Upload Flow (TUS Direct Upload):

1. Teacher clicks "Add Video" → modal: name, order → Video record created (bunny_video_id=null, status="Pending")
2. Teacher clicks "Upload" on the pending row → POST .../create-upload/ → returns TUS credentials
   • ⚠️ 409 Conflict: If another user is already uploading to the same video, create-upload/ rejects with 409. Wait for their upload to finish.
   • ⚠️ 400 Already Finalized: If the video is already in a ready status (3/4), delete and re-create to upload a replacement.
3. Frontend uploads directly to Bunny using tus-js-client:
   • endpoint: https://video.bunnycdn.com/tusupload
   • headers: AuthorizationSignature, AuthorizationExpire, VideoId, LibraryId
   • Zero backend bandwidth/RAM used
4. (Optional) Call POST /courses/videos/<id>/upload-complete/ after TUS onSuccess — faster status detection, but not required
5. Frontend polls GET /courses/videos/<id>/ every 5 seconds — self-healing sync (backend checks Bunny API on each poll)
6. UI shows live status: Created → Uploaded → Processing → Transcoding → Ready ✅
7. When a ready status is reached (3/4), is_active=true, teacher sees "Ready" badge

TUS handles pause/resume natively — findPreviousUploads() + resumeFromPreviousUpload() stores progress in localStorage and resumes at the exact byte. Use 5 MB chunks (chunkSize: 5 * 1024 * 1024) and add 300ms delay between chunks via onChunkComplete to prevent WiFi saturation.

Note: The old POST /upload/ proxy endpoint has been removed (returns 410 Gone).

Video List UI Table:
# │ Name          │ Status                            │ Actions
──┼───────────────┼───────────────────────────────────┼────────────
1 │ Intro         │ ✅ Ready                         │ [Preview] [Delete]
2 │ Types         │ ⬆️ ████████░░ 80% Uploading      │ [Pause] [Cancel]
3 │ Graphs        │ 📝 Pending (not uploaded yet)    │ [Upload] [Delete]
4 │ Advanced      │ ❌ Error — encoding failed        │ [Retry] [Delete]

Playback Preview (teacher): GET /courses/videos/<id>/play/ returns Bunny Stream HLS URL. Teacher can preview own videos.

Student Preview toggle: Add ?as_student=true to any course/topic/lecture detail endpoint to see exactly what students see (only active topics, visible lectures, active videos).

Page 3: Lecture Detail — Students Progress Tab

Purpose: See ALL enrolled students for this lecture — who bought it, who didn't, their homework/quiz scores, watch progress, and reopen expired purchases.

Single API call: GET /courses/lectures/<id>/students-progress/

Reopen purchase: PATCH /courses/purchases/<id>/reopen/ (no body, 1 day, max 2)

The students-progress/ endpoint returns everything in one response (see API_TEACHER.md §8 for full response).

Pagination: Supports ?page= and ?page_size= (default 50, max 200). Response includes count, next, previous, results. Add "Load More" / page navigation when next is not null.

Top-level arrays:

Per-student homeworks[] and quizzes[] always match the length and order of these top-level arrays. Empty array = no assessments of that type.

UI Layout (summary table):

← Back to Lecture Detail

Lecture: Intro to Reactions
Course: Chemistry 3rd Secondary — Teacher: Dr Hany
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total enrolled: 25 students | Purchased: 20 | Not purchased: 5

[Search by student name or code...]  (client-side filter)

Student       │ Code    │ Bought   │ Paid     │ Watch      │ Actions
──────────────┼─────────┼──────────┼──────────┼────────────┼─────────────
Ahmed Ali     │ 1234567 │ ✅ Yes   │ 40 EGP   │ 2/3 (67%)  │ [View]
Sara Ahmed    │ 7654321 │ ❌ No    │ —        │ —          │ [View]
Mohamed Omar  │ 1122334 │ ✅ Yes   │ 40 EGP   │ 3/3 (100%) │ ✅ Active
Nora Hassan   │ 9988776 │ ✅ Yes   │ 40 EGP   │ 0/3 (0%)   │ [View]
Khaled Ali    │ 5544332 │ ✅ Yes   │ 40 EGP   │ 1/3 (33%)  │ 🔴 Expired [Reopen]

Page 1 of 2 — [Next ►]

Each column explained:

Render logic:

[View] button opens a modal/drawer with full student detail (see below). [Reopen] opens a confirmation dialog (see reopen flow below).

Reopen flow:

1. Teacher clicks [Reopen] on an expired row
2. Confirmation dialog: student name, current expiry (expires_at), reopens used (reopen_logs.length), remaining (2 - logs.length), sessions_used will be reset to 0
3. Confirm ? PATCH /courses/purchases/<id>/reopen/ (no body)
4. On success ? re-fetch students-progress/ for that page
5. Access is restored for ~1 day from now (expires_at = max(expiry, now) + 1 day, extra_days resets to 0) — reopening a lecture expired long ago actually works now. is_expired recalculates, can_reopen updates, sessions_used is reset to 0 so the student can start new viewing sessions

[View] Modal — Full Student Detail

When the teacher clicks [View] on any row, a modal/drawer opens showing everything about that student for this lecture. No additional API call needed — all data is already in the students-progress/ response.

Modal layout:

┌─────────────────────────────────────────────────────────────────┐
│  Student: Ahmed Ali (1234567)                               [X] │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ── Purchase Info ────────────────────────────────────────────  │
│  Status:    Purchased ✅                                        │
│  Paid:      40.00 EGP                                           │
│  Purchased: July 1, 2026                                        │
│  Expires:   August 2, 2026 (1 reopen used, 1 remaining)        │
│  Watched:   2/3 videos (67%)                                    │
│                                                                  │
│  ── Homeworks ────────────────────────────────────────────────  │
│  Week 1 HW    │ ✅ Submitted    │ Score: 2/3  │ Jul 1, 2026    │
│  Week 2 HW    │ ❌ Not done     │ —           │ —               │
│                                                                  │
│  ── Quizzes ──────────────────────────────────────────────────  │
│  Quiz 1       │ ❌ Not done     │ —           │ Attempt 0/1    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Modal sections:

Homework table columns:

Quiz table columns:

Empty states inside modal:

• No homeworks exist → section shows "No homeworks for this lecture."
• No quizzes exist → section shows "No quizzes for this lecture."
• Student not purchased → Purchase section shows "Not purchased."

Empty states for the main table:

• No enrolled students → "No students are enrolled in this course yet."
• No videos → watch column shows "—"

Page 4: Homework Bubble Sheet (Standalone + Lecture Tab)

Purpose: Create bubble-sheet homework with questions. View submissions with per-question results.

Standalone management page: Table of all homeworks across courses with filters (?lecture=, ?is_published=).

Lecture tab: Same component, pre-filtered by ?lecture=<id>.

Create form:

Title: [Week 1 Homework______________]
Description: [________________]
Published: [  ] (toggle)
Show grades to students: [  ] (toggle — when on, students see correct answers after submission)

Bubble Questions:
Q1: Choices [4 ▼] | Answer [A] | Explanation (optional): [_________] | Points: [1]
Q2: Choices [5 ▼] | Answer [B] | Explanation (optional): [_________] | Points: [2]
+ Add Question

Bubble Question fields:

• order — question number
• choices_count — number of choices (2–8)
• correct_answer — e.g. "A" or "A,C"
• answer_explanation — shown after submission if show_grades=true
• points — 1–20 (default 1, max 20; enforced by the backend)

Request body:

{
  "lecture": 5,
  "title": "Week 1 HW - Chapter 1",
  "description": "Chapter 1 exercises",
  "is_published": false,
  "bubble_questions": [
    {"order": 1, "choices_count": 4, "correct_answer": "A", "answer_explanation": "Optional", "points": 1},
    {"order": 2, "choices_count": 5, "correct_answer": "A,C", "answer_explanation": "", "points": 2}
  ]
}

Submissions table (teacher view):

Student      │ Code    │ Score │ Status │ Submitted
─────────────┼─────────┼───────┼────────┼──────────────
Ahmed Ali    │ S-001   │ 2/3   │ Graded │ 2026-07-08
Sara Ahmed   │ S-002   │ 3/3   │ Graded │ 2026-07-07

Click a submission → per-question results:

Q1: Student answered B | Correct: A | ❌ Wrong | Explanation: Because...
Q2: Student answered B | Correct: B | ✅ Correct

Page 5: Quizzes (Standalone + Lecture Tab)

Purpose: Create quizzes with standalone questions (text + image + choices). View submissions, manually grade written answers, release scores/answers.

Settings form (5 fields only):

{
  "timer_minutes": 30,
  "score_visibility": "immediate",
  "answers_visibility": "immediate",
  "question_order": "fixed",
  "max_attempts": 1
}

Multi-attempt enforcement (quizzes): Students can start a new quiz attempt while one is in progress (the backend returns the existing in-progress attempt), and can submit up to max_attempts times. When all attempts are used, POST /start/ returns 400 "You have used all your allowed attempts...". The teacher frees a slot by deleting a submission via DELETE /learning/quiz-submissions/<pk>/delete/. Exams remain single-attempt — delete the submission to allow a retake.

Note on is_active: This field exists on the model for frontend hide/show toggling but is not enforced by the backend. Only is_published gates student access. Set is_published=true when the quiz is ready for students.

Questions: Standalone only (inline text + MCQ choices + written).
Images: NOT uploadable via JSON during inline creation. Upload question images separately via PATCH /learning/questions/<id>/ with multipart/form-data (image field). The response always returns the image as a full URL.

Sending questions inline during create/update:

{
  "lecture": 5,
  "title": "Quiz Title",
  "settings": { ... },
  "questions": [
    {
      "text": "What is 2+2?",
      "question_type": "mcq_single",
      "order": 1,
      "points_override": 2,
      "choices": [
        {"text": "4", "is_correct": true, "order": 1},
        {"text": "5", "is_correct": false, "order": 2}
      ]
    }
  ]
}

CAUTION: Sending questions on update (PUT/PATCH /quizzes/<id>/) upserts by question id: existing questions (with matching id) are updated in-place, new questions (no id) are created, questions absent from the payload are deleted. For auto-save without risking deletion, use individual PATCH /questions/<id>/ instead.

Limits: a quiz can have max 300 questions (create and update — 400 otherwise); each question max 20 points (points_override, null = 1).

Page 6: Exams (Standalone Course-Level)

Purpose: Create exams independent of lectures. Can be used as prerequisites.

Settings: Same as quizzes (5 fields) plus AFTER_CLOSE visibility option (exams have open_date/close_date).

Note: Created at course level, not lecture level. Appears in student's Exams page and can gate lecture access via prerequisites.

Single-attempt enforcement (exams only): Exams allow exactly 1 attempt. Teachers can delete a submission via DELETE /learning/exam-submissions/<pk>/delete/ to let a student retake. (Quizzes are multi-attempt — see Page 5.)

Page 7: Study Materials (Lecture Detail → Materials Tab)

Accepted formats: PDF, JPG, JPEG, PNG — Max size: 20 MB
Write access: Teachers and assistants only (students and siteowners are read-only)
File uploads get a unique UUID filename — no overwrites

Page 8: Lecture Prerequisites (Lecture Detail → Prerequisites Tab)

Purpose: Gate lecture video access behind quiz or exam passing scores.

Valid types: quiz, exam

The "available assessments" endpoint returns all quizzes and exams for a lecture in one call — so the prerequisite picker dropdown can be populated with a single request instead of three:

{
  "quizzes": [{ "id": 5, "title": "Quiz 1", "lecture_id": 5, "lecture_name": "Intro to Reactions" }],
  "exams": [{ "id": 2, "title": "Midterm Exam" }]
}

Prerequisite picker UI:

Current prerequisites for "Intro to Reactions":
  - Quiz #1 (must score >= 50%)      [Remove]
  - Quiz #2 (must score >= 70%)      [Remove]

+ Add Prerequisite
  Type: [Quiz ▼]  ID: [____]  Passing Score: [50]%

Page 9: Students Page (Enrollments + Purchases + Balances)

Purpose: Manage everything about every student in a course. Approve/reject enrollments, view balances, purchases, attendance, homework/quiz/exam grades.

Flow Overview:

1. Load page → GET /courses/enrollments/?course=X&status=approved → list of approved students + balances
2. Tabs: Pending | Approved | Rejected
3. Click student → expanded row with per-lecture purchases + homework/quiz/video status
4. Click student → see full details in expanded row (balance, purchases, activity from enrollment list + transactions)

Page layout:

Course: Chemistry 3rd Secondary

Pending (3) | Approved (24) | Rejected (2)

── Pending Tab ──────────────────────────────────────
Gets data from: GET /courses/enrollments/?course=X&status=pending

Student      │ Code    │ Requested    │ Actions
─────────────┼─────────┼──────────────┼────────────────────────────
Ali Hassan   │ S-010   │ 2026-07-07   │ [Approve] [Reject]
Nora Ahmed   │ S-011   │ 2026-07-06   │ [Approve] [Reject]

── Approved Tab ──────────────────────────────────────
Gets data from: GET /courses/enrollments/?course=X&status=approved
(returns: student_id, student_name, student_code, balance, enrolled_at)

Student      │ Code    │ Balance  │ Actions
─────────────┼─────────┼──────────┼────────────────────────────
Ahmed Ali    │ S-001   │ 200 EGP  │ [Report] [Reopen] [History]
  ▶ Expanded (per-lecture data, fetched on expand):
    Data source: GET /courses/enrollments/?course=X&status=approved (enrollment list with balance)
    - Lecture 1: Intro → Bought Jul 1 → Expires Jul 31 → Watch 2/4 → [Reopen]
    - Lecture 2: Types → Bought Jul 3 → Expires Aug 2 → Watch 1/4 → [Reopen]
    - Quiz 1: 80% ✅
    - Homework 1: 2/3

── Full Report (modal / new page) ───────────────────
Data source: GET /payments/transactions/?student=X
(one API call returns everything: student info, enrollment, balance,
 ALL lectures (bought + not bought) with per-lecture progress:
 videos watched, homework submitted, quiz taken, purchases, etc.)

── Balance History (modal) ─────────────────────────
Data source: GET /payments/transactions/?student=X
Shows every transaction with balance_before → balance_after:
 code redemptions (shows code, amount, balance snapshots),
 lecture purchases (shows lecture name, amount deducted, balance snapshots)

Endpoint Reference Table:

Expanded Row Data Flow:

1. Teacher clicks a student row → fetch GET /payments/transactions/ for a specific lecture
2. The report returns per-student data structure: purchased (T/F), amount_paid, expires_at, is_expired, homeworks[], quizzes[], videos[]
3. Render each lecture's data in the expanded row
4. For the students who haven't purchased → purchased: false → show [Buy] prompt instead

Full Report Data Flow:

1. Teacher clicks [Report] → fetch GET /payments/transactions/?student=X
2. Returns everything: student profile, enrollment, balance, ALL lectures (bought + not bought), per-lecture homework/quiz/video progress, ALL purchases, ALL submissions
3. One API call replaces the need for multiple individual calls — complete picture in a single response
4. For balance history drill-down: GET /payments/transactions/?student=X (balance_before → balance_after per action)

Page 10: Student Report

Purpose: Full report of everything about a student within a course.

Response includes: student info, ALL lectures (bought + not bought) with per-lecture homework/quiz/video progress, purchases (with sessions/expiry + can_reopen), quiz submissions, homework submissions.

Balance history (separate): GET /payments/transactions/?student=X — full ledger with balance_before and balance_after for every code redemption and lecture purchase.

Page 11: Assistants Page (Teachers Only)

Purpose: Manage assistants who share all course management capabilities.

Note: Assistant creation is teacher-only. Assistants can view other assistants but cannot create/delete.

Page 12: Codes Page (Teacher + SiteOwner)

Purpose: Generate, track, and export recharge codes. Codes are money — every action is audited.

Roles: SiteOwner (all courses), Teacher (own courses only). Assistant can view their teacher's codes.

Page Layout (3 views):

┌──────────────────────────────────────────────────────────────────┐
│  Analytics Cards: Total Batches | Codes | Valid | Used |        │
│  Blacklisted | Revenue Collected                                │
├──────────────────────────────────────────────────────────────────┤
│  Filter Bar: [Teacher ▼] [Course ▼] [Clear]  Showing 12 batches │
├──────────────────────────────────────────────────────────────────┤
│  Batch List Table:                                               │
│  Batch ID │ Course │ Teacher │ Codes │ Value │ Status │ Notes   │
│  Batch #1 │ Chem   │ Dr Hany │ 100   │ 50    │ ████░░ │ Center  │
│  Batch #2 │ Phys   │ Omar    │ 50    │ 100   │ ██░░░░ │ School  │
├──────────────────────────────────────────────────────────────────┤
│  Pagination                                                     │
└──────────────────────────────────────────────────────────────────┘

Click a batch row → View individual codes in that batch:

┌──────────────────────────────────────────────────────────────────┐
│  ← Back to Batches                                              │
│  Batch #1 — Chemistry 3rd Secondary — Dr Hany Hassanin          │
│  Codes: 100 | Value: 50 EGP | Redeemed Value: 17,500 EGP       │
├──────────────────────────────────────────────────────────────────┤
│  Code (masked)  │ Value │ Status   │ Used By       │ Used At     │
│  X7K9 XXXX…    │ 50    │ ✅ Used │ Ahmed / أحمد  │ 2026-07-14  │
│  A1B2 XXXX…    │ 50    │ 🟢 Valid │ —             │ —           │
└──────────────────────────────────────────────────────────────────┘

Click "History" → Full audit modal with date/type/code filters.
Click "Blacklist" → OTP verification → irreversible blacklist.

APIs for the Page:

Analytics Cards (from GET /codes/analytics/):

Note: Teacher's Cut / SiteOwner's Cut cards were removed from the backend — GET /payments/codes/analytics/ returns only the 8 fields above. The video_security.price_per_student platform-fee split is no longer computed.

Code Model Fields:

Code Status Flow:

Valid ──→ Redeemed (used)     — Student self-redeem or Teacher recharge
Valid ──→ Blacklisted         — SiteOwner only, OTP required, irreversible

Business Rules:

• Codes are course-specific — can only be redeemed for the course they were generated for
• If the course is deleted, all its codes are permanently deleted (CASCADE)
• If the course is deactivated, codes remain valid but cannot be redeemed
• Cannot delete a code (financial records)
• Cannot edit value or expiry after creation
• Expiry is 1 year from creation (not changeable)
• Race-condition-safe with select_for_update() — no double-redemption possible
• Every code action creates an immutable BalanceTransaction (source of truth for finances)
• Batch name format is "{TeacherName} Batch #{n}" where n is a per-teacher sequential counter

Excel Export Columns (from GET /codes/export/?batch=<uuid>): Code | Value (EGP) | Status | Course | Redeemed By | Redeemed At | Blacklisted By | Blacklisted At | Created At | Expires At | Notes

Page Flow for SiteOwner:

1. Page loads → GET /payments/codes/analytics/ → populate analytics cards (Total Batches, Codes, Valid, Used, Blacklisted, Revenue Collected)
2. GET /payments/codes/batches/ → populate batch table (paginated, 20 per page)
3. Teacher dropdown → GET /payments/codes/batches/?teacher=X → filter batches
4. Course dropdown (dependent on teacher) → GET /payments/codes/batches/?course=X → filter batches
5. Click batch row → GET /payments/codes/batches/<uuid>/ → show individual codes with `code_masked` ("ABDC XXXX XXXX XXXX") by default, "Reveal" button to show full code
6. Click "Export" on batch → GET /payments/codes/export/?batch=<uuid> → download .xlsx
7. Click "Export All" → GET /payments/codes/export/ → download all codes .xlsx
8. Click "History" → open modal → GET /payments/codes/history/ with default date range (last 30 days) → populate history table with filters
9. In History modal: filter by type, code search, date range → refetch or client-filter
10. Click "Generate Batch" → POST /payments/codes/ → modal with course/count/value/notes
11. Select one or more codes via checkboxes → Click "Blacklist Selected" → POST /codes/request-blacklist-otp/ → OTP modal
12. Enter OTP → POST /codes/batch-blacklist/ with { code_ids: [...] } → codes permanently blacklisted

Page Flow for Teacher (same as above, but:

• No teacher dropdown (auto-filtered to their own data)
• "Generate Batch" creates codes for their own courses only
• Analytics show only their own codes
• Batch list shows only their own batches

Page 12: Course Dashboard (Unified — Built Last)

When all features exist, build a single page that unifies everything into 4 tabs:

┌────────────────────────────────────────────────────────────┐
│  ← Chemistry 3rd Secondary                                 │
│                                                            │
│  ┌──────────┬─────────────────────┬──────────┬───────────┐ │
│  │  📊     │  👥                 │  📚     │  📋       │ │
│  │Overview │ Students            │ Content  │ Reports   │ │
│  │ (Stats) │ Same as Page 9      │ Same as  │ Same as   │ │
│  │         │ (embedded)          │ Page 2   │ Page 10   │ │
│  │         │                     │ (embedded)│ (embedded)│ │
│  └──────────┴─────────────────────┴──────────┴───────────┘ │
└────────────────────────────────────────────────────────────┘

Tab 1 — Overview: GET /courses/<id>/ — enrolled/pending/rejected counts, topic/lecture/video counts.
For deeper analytics: GET /courses/<id>/analytics/ — per-topic and per-lecture purchase breakdowns with revenue.

Page 13: Teacher Dashboard (Last — Standalone)

Purpose: Landing page after teacher login. Aggregated stats across all courses, plus action items that need the teacher's attention. Single call to GET /courses/teacher/dashboard/ replaces multiple API calls.

GET /courses/teacher/dashboard/ Response:

{
  "summary": {
    "total_courses": 3,
    "active_courses": 3,
    "total_students": 24,
    "pending_enrollments": 4,
    "total_purchases": 18,
    "total_revenue": "720.00",
    "outstanding_cut": "160.00"
  },
  "actions_needed": {
    "pending_enrollments": [
      {
        "enrollment_id": 1,
        "student_id": 10,
        "student_name": "Ahmed Ali / أحمد",
        "student_code": "1234567",
        "course_id": 28,
        "course_name": "Chemistry 3rd Secondary 2027",
        "enrolled_at": "2026-07-30T10:00:00Z"
      }
    ],
    "ungraded_written": {
      "total_pending": 5,
      "quizzes": [
        { "quiz_id": 94, "quiz_title": "Important Quiz", "lecture_name": "Lecture 1", "course_name": "...", "pending_count": 3 }
      ],
      "exams": [
        { "exam_id": 2, "exam_title": "Midterm", "course_name": "...", "pending_count": 2 }
      ]
    }
  },
  "recent_enrollments": [
    { "id": 1, "student_name": "Ahmed Ali / أحمد", "student_code": "1234567", "course_name": "Chemistry 3rd Secondary 2027", "status": "pending", "enrolled_at": "2026-07-30T10:00:00Z" }
  ],
  "recent_purchases": [
    { "id": 1, "student_name": "Ahmed Ali / أحمد", "student_code": "1234567", "lecture_name": "Lecture 1", "course_name": "Chemistry 3rd Secondary 2027", "amount_paid": "40.00", "purchased_at": "2026-07-30T11:00:00Z" }
  ],
  "courses": [
    { "id": 28, "name": "Chemistry 3rd Secondary 2027", "is_active": true, "enrolled_count": 10, "pending_count": 2, "purchase_count": 8, "revenue": "320.00" }
  ]
}

Page layout:

Dashboard — Welcome back, Dr Hany
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Summary cards]
  Total Courses: 3 (2 active) │ Students: 24 │ Purchases: 18 │ Revenue: 720 EGP

[Actions Needed]                                     ← NEW — teacher's to-do list
  ┌─ Pending Enrollments (4) ──────────────────────────────────┐
  │ Ahmed Ali / أحمد (1234567) — Chemistry 3rd Sec 2027       │
  │   requested Jul 30                          [Approve] [Reject] │
  └────────────────────────────────────────────────────────────┘
  ┌─ Ungraded Written Answers (5) ─────────────────────────────┐
  │ Quiz: Important Quiz (Lecture 1, Chemistry) — 3 pending   │
  │   → link to quiz written-answers review                    │
  │ Exam: Midterm (Chemistry) — 2 pending                     │
  │   → link to exam written-answers review                    │
  └────────────────────────────────────────────────────────────┘

[Recent Activity]
  Recent Enrollments (last 10) — table: student, code, course, status, date
  Recent Purchases (last 10)   — table: student, code, lecture, course, amount, date

[Course Breakdown]
  Course card grid — name, active badge, enrolled/pending counts,
  purchase count, revenue, "Open" → Content Management

Field usage guide:

Business rules for the frontend:

• actions_needed.pending_enrollments is the full list (not capped at 10) — the card can scroll or show all. Count badge = summary.pending_enrollments.
• Approving/rejecting from the dashboard works exactly like the Students page: POST /courses/enrollments/approve/ {enrollment_ids: [...], response_note?} — 200 response {processed, total_requested, errors}.
• amount_paid and revenue are strings (decimal) — format, don't parse as floats.
• Empty states: no courses → "Create your first course"; no recent enrollments/purchases → "No recent activity".
• Only one API call per page load; re-fetch after approve/reject actions to update all sections.

Page 14: Cut Invoices (SiteOwner) + My Cuts (Teacher)

Purpose (SiteOwner): Manual platform-cut invoicing. Siteowner sees per-teacher lecture volume (filterable by month/date range), creates an invoice with a date range + cut per lecture, and tracks unpaid/paid/cancelled invoices. Purpose (Teacher): see their own invoices (owed/settled) — transparency.

APIs (SiteOwner — all under /payments/cuts/):

API (Teacher):

SiteOwner page layout (/siteowner/cuts):

Filter bar: [Teacher ▼] [Search...] [Start date] [End date] [Clear]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary cards: Total Lectures | Purchased Lectures | Outstanding | Collected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overview table (per teacher):
Teacher      │ Lectures │ Purchased │ Outstanding │ Paid │ Actions
Dr Hany     │ 42       │ 320       │ 6400 EGP    │ 1200 │ [Create Invoice] [▸ Expand]
  ▸ per-course rows: course name, grade, lectures, purchased, revenue
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Invoices table:
Teacher │ Period          │ Count │ Cut/Lec │ Total    │ Status  │ Actions
Dr Hany │ Aug 1–31, 2026  │ 320   │ 20 EGP  │ 6400 EGP │ Unpaid  │ [Mark Paid] [Cancel] [View]

Create Invoice modal: teacher (pre-filled), start/end dates, cut_per_lecture, discount, note. Live preview: "N lectures in range × X EGP − discount = Y EGP" (N fetched from /cuts/lectures/?teacher=&start=&end=; validate discount ≤ gross client-side, server enforces too). Overlapping-period and discount>gross errors (400) shown inline.

Mark Paid flow: optional Payment Note field → PATCH {status: "paid", paid_note}. Reverting to unpaid clears the note.

Invoices table: teacher | period | count | cut/lecture | discount | gross | total | status badge | paid note | actions.

Teacher page (/teacher/cuts): read-only table of their invoices — period, lectures count, cut, discount, gross/total owed, status badge, note, paid note. Empty state "No invoices yet."

Business rules (backend-enforced):

• lectures_count is a snapshot at creation; editing the cut/discount never re-counts.
• total_owed = max(0, (cut × count) − discount); gross_total = cut × count (read-only).
• Overlapping unpaid/paid invoices for the same teacher are rejected (cancelled ones don't block).
• Paid invoices lock the cut AND discount; teacher + period are immutable.
• DELETE soft-cancels; paid → unpaid/cancelled clears paid_at and paid_note.
• ?search= is case-insensitive partial: overview → teacher name; lectures → student name/code/lecture/course; invoices → teacher name/note; cuts/my/ → note.

Phase 3: Student Pages (Build After Phase 2)

Build in dependency order. Pages without dependencies can be built in parallel.

Dependency graph:

Early (independent):
  Page 1: Profile
  Page 2: Recharge Codes
  Page 3: Transaction History

Chain (build in order):
  Page 4: Course Preview
       ↓
  Page 5: My Enrollments
       ↓
  Page 6: Course Lectures
       ↓
  Page 7: Purchase Lecture
       ↓
  Page 8: Lecture Player

Independent (can build anytime after Chain):
  Page 9: Homework Bubble Sheet
  Page 10: Quiz Taking
  Page 12: My Lectures (aggregate — all purchased lectures)
  Page 13: My Homeworks (aggregate — all available homeworks)
  Page 14: My Quizzes (aggregate — all available quizzes)

Last (build after everything):
  Page 11: Student Dashboard

Student authentication behavior by status: After login (POST /accounts/login/), the response includes status for students:

• pending → Show "pending approval" message — can't access courses yet
• verified → Normal login — full access
• declined → Receive {status: "declined"} — show reason + prompt to edit profile (editing resets to pending)
• suspended_temporary → Receive {status: "suspended_temporary"} — show reason
• suspended_permanent → Blocked — 401 "Your account has been permanently suspended."

Page 1: Profile (Independent — Build Any Time)

Purpose: View profile + change password + edit profile if declined. No student-page dependencies — can be built immediately after Phase 1.

APIs to use (from API_STUDENT.md):

GET /accounts/profile/me/ Response:

{
  "id": 1, "user_id": 1, "username": "ahmed123",
  "student_code": "1234567",
  "name_ar": "أحمد", "name_en": "Ahmed",
  "full_name": "Ahmed / أحمد",
  "phone_number": "01234567890",
  "father_number": "01112345678",
  "mother_number": "01087654321",
  "school_type": 1, "school_type_name": "Public School",
  "grade": 3, "grade_name": "3rd Secondary",
  "division": 2, "division_name": "Scientific",
  "school_name": "Al-Haram Secondary School",
  "birth_date": "2008-05-15",
  "gender": "male",
  "gmail": "ahmed@gmail.com",
  "governorate": 1, "governorate_name": "Cairo",
  "area": 5, "area_name": "Nasr City",
  "status": "declined",
  "is_active": false,
  "can_access_course": false,
  "status_history": [
    {
      "from_status": "pending",
      "to_status": "declined",
      "reason": "Missing father's phone number. Please re-submit with correct info.",
      "changed_by": "Admin � Username of the admin who made the change",
      "created_at": "2026-07-15T10:00:00Z"
    }
  ],
  "created_at": "2026-06-01T10:00:00Z",
  "updated_at": "2026-07-18T10:00:00Z"
}

PATCH /accounts/profile/me/ Request: Same fields as GET (all optional for PATCH). Can use JSON or multipart. Only sends if status === 'declined'.

POST /accounts/change-password/ Request:

{
  "old_password": "String (Required) — Current password",
  "new_password": "String (Required) — Minimum 8 characters",
  "new_password_confirm": "String (Required) — Must match new_password"
}

POST /accounts/change-password/ Response — 200 OK:

{
  "message": "Password changed successfully. Please log in again."
}

Error Responses:

Page layout:

• Purple banner at top with welcome message and stats (profile completion, status)
• Status alert banner: For declined → shows reason from status_history in a warning card with edit prompt
• Profile form: Two-column grid with fields (name_ar, name_en, phone, school info, location, etc.)
  • Status badge shown inline
  • Edit enabled only when status === 'declined'
• Change password section: Old password, new password, confirm new password
• Business rules table:

  Status	Can edit profile?	Can change password?
  verified	❌	✅
  pending	❌	✅
  declined	✅ (resets to pending)	✅
  suspended_temporary	❌	✅
  suspended_permanent	❌ Blocked from login	❌

Populates from: profile endpoint

Page 2: Recharge Codes (Independent — Build Any Time)

Purpose: Redeem physical voucher codes to add balance to a specific course.

APIs to use (from API_STUDENT.md):

POST /payments/codes/redeem/ Request:

{"code": "X7K9-M2P4-QR1W-L5D8", "course": 1}

POST /payments/codes/redeem/ Response — 200 OK:

{
  "detail": "Code redeemed successfully. Added 50.00 EGP to your Chemistry balance.",
  "new_balance": "200.00",
  "transaction_id": 42
}

Error Responses:

Page layout:

• Purple banner with page title
• Balance cards: For each enrolled course show course name, teacher, current balance
• Redeem section: Course dropdown, code input (auto-format dashes), Redeem button
  • Course dropdown only shows courses where student is approved-enrolled
  • On success → new_balance shown, balance list refreshes

Populates from: balance endpoint for course list + balances; redeem for code application

Page 3: Transaction History (Independent — Build Any Time)

Purpose: View full ledger of all code redemptions and lecture purchases with per-course balance tracking.

API: GET /payments/transactions/ — auto-filtered to the logged-in student. Paginated.

Query Parameters:

Response:

{
  "count": 12,
  "results": [
    {
      "course_name": "Chemistry 3rd Secondary",
      "teacher_name": "Dr Hany Hassanin",
      "teacher_picture": "https://.../profile_pictures/drhany.jpg",
      "transaction_type": "code_redeemed",
      "transaction_type_display": "Code Redeemed",
      "amount": "50.00",
      "balance_before": "100.00",
      "balance_after": "150.00",
      "description": "Code X7K9-M2P4-QR1W-L5D8",
      "created_at": "2026-07-19T10:00:00Z"
    }
  ]
}

Page layout:

• Summary cards: Total Redeemed (green), Total Spent (red), Current Balance (brand color)
• Filters: Course dropdown, Type dropdown (All/Code Redeemed/Lecture Purchased), Search input, Clear button
• Ledger table:

  Date	Type	Teacher	Description	Performed by	Amount	Balance After
  Jul 19	Redeemed ✅	Dr Hany	Code X7K9-...	Teacher name	+50.00	150.00 (was 100)
  Jul 18	Purchased 🔶	Dr Hany	Intro to Reactions	Student	−40.00	100.00 (was 140)

• Pagination with page numbers

Populates from: transactions endpoint

Page 4: Course Preview

Purpose: Preview a course before enrolling — shows full structure with topics, lectures, prices, and teacher info. Available to any authenticated user.

APIs to use (from API_STUDENT.md):

GET /courses/<id>/preview/ Response:

{
  "id": 1, "name": "Chemistry 3rd Secondary",
  "description": "Full course covering chemical reactions...",
  "cover_picture": "https://.../cover.jpg",
  "teacher": {"id": 5, "name": "Dr Hany", "profile_picture": "..."},
  "grade": {"id": 3, "name": "3rd Secondary"},
  "subject": {"id": 2, "name": "Chemistry"},
  "topic_count": 5, "total_lectures": 20,
  "topics": [
    {
      "id": 1, "name": "Chemical Reactions",
      "lecture_count": 4,
      "picture": "https://.../topics/pictures/chemical.jpg",
      "lectures": [
        {
          "id": 10, "name": "Intro to Reactions",
          "price": "50.00", "final_price": "40.00",
          "discount": "10.00", "available_days": 30,
          "video_count": 2
        }
      ]
    }
  ]
}

Page layout:

• Course hero: Cover image (left), course name + grade badge + teacher info (name, initials, subject) on right
• No course description section (backend's description field is for internal use — not shown to students)
• Course Curriculum card: Expandable topic cards with thumbnail images
  • Each topic card: thumbnail image, topic name, lecture count
  • Click to expand → lecture list with names
• Instructor card: Teacher avatar, name, subject, bio text
• Side card: Course cover thumbnail, "Enroll for Free" button
• Eligibility gate (new): for authenticated students, the preview response includes eligibility: {eligible, reason: 'grade'|'division'|'school_type'|null}. If eligible: false, hide the "Enroll for Free" button and show the reason (e.g., "This course is for another grade/division"). Course lists (/courses/, /courses/by-subject/<id>/) are already filtered server-side to eligible courses, so this mostly guards direct links.
• Enroll flow:
  • Not enrolled → "Enroll for Free" → POST /courses/enrollments/enroll/ with {"course": <id>}
  • Enrollment response includes status (pending) — redirect to My Enrollments

Populates from: preview endpoint for course data; enroll for enrollment

Page 5: My Enrollments

Purpose: View all enrolled courses with teacher info, topics/lectures count. Each card links to the course lectures page.

APIs to use (from API_STUDENT.md):

GET /courses/enrollments/ Response (student view):

[
  {
    "id": 1, "student": 1,
    "student_name": "Ahmed / ????", "student_code": "1234567",
    "course_name": "Chemistry 3rd Secondary",
    "grade_name": "3rd Secondary",
    "teacher_name": "Dr Hany",
    "subject_name": "Chemistry",
    "status": "approved",
    "status_display": "Approved",
    "balance": "150.00",
    "cover_picture": "https://.../covers/chem.jpg",
    "topic_count": 5,
    "total_lectures": 20,
    "enrolled_at": "2026-07-01T10:00:00Z",
    "responded_by": null,
    "responded_by_name": null,
    "responded_at": null,
    "response_note": null
  }
]

Note: cover_picture, topic_count, total_lectures are only non-null for approved enrollments.

Page layout:

• Page title: "My Enrollments"
• Course cards grid: Each card shows:
  • Cover image (from cover_picture)
  • Course name
  • Teacher name
  • Topics count, lectures count (from topic_count, total_lectures)
  • "Continue Learning" button ? links to Course Lectures (Page 6)
• Empty state: "No enrollments yet"

Populates from: enrollments endpoint with ?status=approved

Page 6: Course Lectures

Purpose: View all topics inside an enrolled course. Each topic is a clickable square card that navigates to the lecture player or purchase page.

APIs to use (from API_STUDENT.md):

GET /courses/<id>/lectures/ Response:

{
  "course": {"id": 1, "name": "Chemistry 3rd Secondary"},
  "topics": [
    {
      "id": 1, "name": "Chemical Reactions", "order": 1,
      "lectures": [
        {
          "id": 10, "name": "Intro to Reactions",
          "price": "50.00", "final_price": "40.00",
          "order": 1, "video_count": 2,
          "is_purchased": true,
          "purchase": {
            "id": 5, "purchased_at": "2026-07-01T10:00:00Z",
            "expires_at": "2026-07-31T10:00:00Z",
            "effective_expiry": "2026-07-31T10:00:00Z",
            "is_expired": false, "amount_paid": "40.00",
            "extra_days": 0,
            "max_watch_count": 4,
            "sessions_used": 1,
            "sessions_remaining": 3,
            "has_active_session": true,
            "active_session": {
              "id": 1, "purchase": 5,
              "started_at": "2026-07-26T10:00:00Z",
              "expires_at": "2026-07-26T16:00:00Z",
              "is_active": true,
              "remaining_seconds": 18000
            }
          }
        }
      ]
    }
  ]
}

Page layout:

• Course header: Cover thumbnail + course name + teacher name
• Topic grid: 4-column grid of square topic cards (aspect-ratio: 1)
  • Each card: thumbnail image, topic name, lecture count
  • Click card:
    • If any lecture in topic is purchased → navigate to Lecture Player (Page 8)
    • If no lectures purchased → navigate to Purchase Lecture (Page 7) for the first unpurchased lecture

Populates from: lectures endpoint — topics with lecture purchase status

Page 7: Purchase Lecture

Purpose: View lecture details and purchase access by deducting from course balance.

APIs to use (from API_STUDENT.md):

POST /courses/purchases/buy/ Request:

{"lecture": 10}

Response — 201 Created:

{
  "id": 5, "lecture_name": "Intro to Reactions",
  "topic_name": "Chemical Reactions",
  "course_name": "Chemistry 3rd Secondary",
  "teacher_name": "Dr Hany",
  "purchased_at": "2026-07-18T10:00:00Z",
  "expires_at": "2026-08-17T10:00:00Z",
  "amount_paid": "40.00",
  "is_expired": false
}

Error Responses:

Page layout:

• Lecture locked section (shown when not purchased):
  • Lock icon banner with "Purchase to access this lecture"
  • Lecture info: Topic tag, lecture name, course + teacher
  • Description — from lecture.description
  • Specs grid (3 cards):
    • Video count (video_count)
    • Session limit (max_watch_count) � shown as "X viewing sessions included"
    • Has quiz indicator (from available-assessments endpoint)
    • Has homework indicator
  • Prerequisites list (from LecturePrerequisite model):
    • Each prereq item: name + passed/not passed status
• Purchase card:
  • Price: final_price (with price strikethrough if discounted)
  • Available days: available_days — shown as "Access for X days after purchase"
  • Balance: Current course balance
  • Purchase button (disabled if insufficient balance)
  • Recharge link → Recharge Codes (Page 2)
  • Code section: Input + Apply button for recharge code

Populates from: courses/lectures/<id>/ for lecture detail; buy endpoint; balance endpoint

Page 8: Lecture Player

Purpose: Watch purchased lecture videos, access materials, view quizzes and homeworks. Entry points: Course Lectures page (Page 6) and My Lectures page (Page 12).

APIs to use (from API_STUDENT.md):

GET /courses/videos/<id>/play/ Response:

{
  "playback_url": "https://vz-...b-cdn.net/{guid}/playlist.m3u8"
}

Access Rules:

Session-based viewing (new flow): Instead of per-video watch counting, the system uses 6-hour viewing sessions. The frontend must check session status before showing the player:

1. On entering the lecture player page, call GET /courses/purchases/<pk>/active-session/ to check session status
2. Based on response, show one of 3 UI states:

• When the 6-hour session expires, the play endpoint returns 403. Call GET /active-session/ again to refresh state.
• On page refresh, GET /active-session/ restores the session state � no need to re-start.

Page layout:

• Dark topbar with breadcrumb nav back to Course Lectures
• Session status bar (between breadcrumb and player):
  • Active session: green bar showing "Session active � X hours Y minutes remaining"
  • No active session + remaining: blue bar with "Start watching" button + "X sessions remaining"
  • No remaining sessions: red bar with "All sessions used. Contact teacher." message
• Video player: 16:9 aspect ratio, max 854px wide (YouTube-sized) � not full width
• Video info: Lecture name, topic name, teacher, "Video X of Y" indicator
• Tabs below player: Overview | Materials
  • Overview tab: Lecture description + buttons for "Take Quiz" and "Do Homework"
  • Materials tab: Downloadable files (name, size, Download button)
• Quizzes section (below tabs): Cards for each quiz:
  • Title, question count, status badge (Passed/Failed/Pending), score, action button ("View Results" / "Start Quiz")
  • Click "Start Quiz" ? navigate to Quiz Taking (Page 10)
• Homeworks section (below tabs): Cards for each homework:
  • Title, question count, status badge (Done/Pending), score, action button ("View Submission" / "Start Homework")
  • Click "Start Homework" ? navigate to Homework Bubble Sheet (Page 9)
• Right sidebar: Playlist of other videos in this lecture (prev/next navigation)

Progress tracking (important � read carefully):

The system tracks two independent values. Both must reach >= 90% for is_completed:

Frontend logic (client-side):

// Track cumulative watch time in localStorage (survives page refreshes)
const STORAGE_KEY = `watch_time_${videoId}`;
let cumulativeSeconds = Number(localStorage.getItem(STORAGE_KEY)) || 0;
let lastTick = Date.now();

videoPlayer.on('timeupdate', () => {
  const now = Date.now();
  const elapsed = (now - lastTick) / 1000;  // Real seconds passed
  
  if (!videoPlayer.paused) {
    cumulativeSeconds += elapsed;
    localStorage.setItem(STORAGE_KEY, Math.round(cumulativeSeconds));
  }
  
  lastTick = now;
});

Milestone detection � send cumulative_watch_seconds only 4-6 times total per video:

const DURATION = 600; // video length in seconds
const MILESTONES = [0.25, 0.50, 0.75, 0.90];
let lastReportedMilestone = -1;

function checkMilestone() {
  const milestone = Math.floor(cumulativeSeconds / DURATION / 0.25);
  if (milestone > lastReportedMilestone && milestone < MILESTONES.length) {
    lastReportedMilestone = milestone;
    
    fetch('/courses/progress/update/', {
      method: 'POST',
      body: JSON.stringify({
        video: videoId,
        progress_seconds: Math.round(videoPlayer.currentTime),  // current position
        cumulative_watch_seconds: Math.round(cumulativeSeconds), // cumulative time (milestone)
        duration_seconds: DURATION
      })
    });
  }
}

On tab close (beforeunload): Send one final update with the latest cumulative_watch_seconds.

Example: 10-min video (600s), student watches normally:

Total requests per video: ~6 (4 milestones + 2-3 regular position updates + 1 on close)

Populates from: active-session endpoint (on load), start-watching endpoint (to start session), play endpoint (after session active), materials endpoint, quizzes/ and homeworks/ endpoints

Page 9: Homework Bubble Sheet (Standalone Page)

Purpose: Answer bubble-sheet homework — no question text, just A/B/C/D choices in a compact grid. Opened from Lecture Player's homework card.

APIs to use (from API_STUDENT.md):

GET /learning/homeworks/<id>/ Response (student view):

{
  "id": 1, "lecture": 10,
  "title": "Week 1 HW",
  "description": "Chapter 1 exercises",
  "bubble_questions": [
    {"id": 1, "order": 1, "choices_count": 4},
    {"id": 2, "order": 2, "choices_count": 5}
  ]
}

Note: HomeworkBubbleQuestion has NO text field — only order, choices_count, correct_answer, points.

POST /learning/homeworks/<id>/submit/ Request:

{
  "bubble_answers": [
    {"bubble_question_id": 1, "selected_choice": "A"},
    {"bubble_question_id": 2, "selected_choice": "B,D"}
  ]
}

Response — 200 OK:

{
  "detail": "Homework submitted and auto-graded.",
  "submission_id": 10, "score": "2.00", "status": "graded"
}

Page layout (compact — no scroll):

• Dark topbar with breadcrumb back to Lecture Player
• Header bar: Homework title, question count, points per question
• Bubble sheet table: Single scrollable column, no page scroll
  • Columns: # | Answer (selected choice letter) | A | B | C | D
  • Each row = one question (numbered 1..N)
  • Circles (~28px): click to select. Selected circle fills with brand color.
  • After submit: green = correct, red = wrong. Correct answers also highlighted.
• Footer: Answered/unanswered count with progress bar, Submit button, Back link
• Result bar (after submit): Score (e.g. "105 / 150"), inline Back link
• No question text shown — matches HomeworkBubbleQuestion model (only order + choices_count)

Populates from: homeworks/<id> for questions; draft for save/load; submit for grading; homework-submissions/<id> for results

Page 10: Quiz Taking (Standalone Page)

Purpose: Take a timed quiz one question at a time with navigator, auto-save drafts, and view detailed results after submission.

APIs to use (from API_STUDENT.md):

POST /learning/quizzes/<id>/start/ Response:

{
  "submission_id": 15,
  "timer_minutes": 30, "started_at": "2026-07-18T10:00:00Z",
  "questions": [
    {
      "answer_id": 50, "quiz_question_id": 10,
      "text": "What is 2+2?", "image": null,
      "question_type": "mcq_single", "points": 2,
      "choices": [{"id": 100, "text": "4", "order": 1}, {"id": 101, "text": "5", "order": 2}]
    }
  ]
}

POST /learning/quizzes/<id>/submit/ Request:

{
  "answers": [
    {"quiz_question_id": 10, "choice_ids": [100], "written_answer": ""}
  ]
}

Response — 200 OK:

{
  "detail": "Quiz submitted successfully.", "submission_id": 15,
  "score": "5.00", "score_visible": true, "answers_visible": true
}

Settings fields (from QuizSettings):

Page flow:

1. Start screen: Quiz title, question count, settings displayed (timer, max attempts, score/answer visibility, question order). "Start Quiz" button.
2. Quiz in progress (after start):
   • Timer countdown in header (if timer_minutes > 0)
   • Question navigator: Circle dots for each question — active (filled brand), answered (green outline), unanswered (empty). Click to jump.
   • One question per page: Question text, choices (radio for mcq_single, checkbox for mcq_multiple), Previous/Next buttons
   • Auto-save: Call PATCH /learning/quiz-answers/<answer_id>/save-draft/ on answer change
   • Submit button at bottom
3. On page refresh: GET /learning/quizzes/<id>/resume/ → restore timer, questions, saved answers
4. Results screen (after submit):
   • Score (X / Y), Passed/Failed status
   • Attempt number, time taken, started time, finished time
   • "Back to Lecture" link

Populates from: quizzes/<id> for info; start for beginning; resume for recovery; save-draft for auto-save; submit for grading; quiz-submissions/<id> for results

Page 11: Student Dashboard (Build Last)

Purpose: Landing page after student login. Shows enrolled courses and quick links to all features. Uses the consolidated dashboard endpoint � replaces 5 separate API calls.

APIs to use (from API_STUDENT.md):

GET /courses/student/dashboard/ Response:

{
  "enrolled_courses": [
    {
      "id": "integer",
      "name": "string",
      "cover_picture": "string (URL) | null",
      "teacher_name": "string",
      "teacher_picture": "string (URL) | null",
      "grade_name": "string",
      "balance": "string (decimal)",
      "total_lectures": "integer",
      "purchased_lectures": "integer"
    }
  ],
  "my_lectures": {
    "total": "integer",
    "active": "integer",
    "expired": "integer"
  },
  "nearly_expired_lectures": [
    {
      "purchase_id": "integer",
      "lecture_id": "integer",
      "lecture_name": "string",
      "topic_name": "string",
      "course_name": "string",
      "expires_at": "datetime (ISO 8601)",
      "remaining_hours": "integer"
    }
  ],
  "homeworks": {
    "total": "integer",
    "submitted": "integer",
    "graded": "integer",
    "pending": "integer"
  },
  "quizzes": {
    "total": "integer",
    "not_started": "integer",
    "in_progress": "integer",
    "submitted": "integer"
  }
}

Page layout:

• Page title: "Dashboard"
• Quick Access cards:
  • My Lectures card: Total purchased lectures count, active/expired breakdown from my_lectures, "View All" button ? My Lectures page
  • My Homeworks card: Submitted/graded/pending counts from homeworks, "View All" button ? My Homeworks page
  • My Quizzes card: Not started / in progress / submitted counts from quizzes, "View All" button ? My Quizzes page
• My Enrollments card: List of enrolled courses from enrolled_courses[] (cover thumbnail, course name, teacher name, balance, teacher picture)
• Nearly Expired Lectures: Section listing lectures from nearly_expired_lectures[] with remaining hours countdown
• Quick links: Recharge Codes, Profile Settings, Transaction History

Populates from: /courses/student/dashboard/ (single call � replaces 5 separate API calls)

Page 12: My Lectures (Aggregate)

Purpose: View all purchased lectures across all enrolled courses. Filter and navigate to watch. APIs to use (from API_STUDENT.md �14):

GET /courses/my-lectures/ Response:

[
  {
    "purchase_id": 1, "lecture_id": 10, "lecture_name": "Intro to Reactions",
    "topic_id": 1, "topic_name": "Chemical Reactions",
    "course_id": 1, "course_name": "Chemistry 3rd Secondary",
    "teacher_name": "Dr Hany",
    "price": "40.00",
    "purchased_at": "2026-07-01T10:00:00Z",
    "expires_at": "2026-07-31T10:00:00Z",
    "effective_expiry": "2026-07-31T10:00:00Z",
    "is_expired": false,
    "extra_days": 0,
    "max_watch_count": 4,
    "sessions_used": 1,
    "sessions_remaining": 3,
    "has_active_session": false,
    "video_count": 3,
    "materials_count": 2,
    "homeworks_count": 1,
    "quizzes_count": 1
  }
]

Page layout:

• Page title + subtitle showing total purchased count
• Filters: Course dropdown, Status dropdown (Active/Expired)
• Card grid � grouped by course then sorted by topic: Each card shows:
  • Course name + teacher name (group header)
  • Lecture name, topic name
  • Purchase date, expiry date, effective expiry
  • Active/Expired badge. If active: show session status ("Active session" / "X sessions remaining"). If expired: red badge.
  • Content summary: "X videos � Y materials � Z homeworks � W quizzes"
  • "Watch" button (if active) ? Lecture Player | "Expired" disabled state
• Empty state: "No purchased lectures yet. Enroll in a course and buy lectures to get started."

Populates from: my-lectures endpoint (single call � no more iteration across courses)

Page 13: My Homeworks (Aggregate)

Purpose: View all available homeworks across all purchased lectures. Start homework or view submission results.

APIs to use (from API_STUDENT.md �14):

GET /learning/homeworks/ Response (paginated � use /learning/homeworks/?all=true for non-paginated):

[
  {
    "homework_id": 1,
    "title": "Week 1 HW",
    "description": "Chapter 1 exercises",
    "is_published": true,
    "show_grades": true,
    "total_points": 3,
    "lecture_id": 10,
    "lecture_name": "Intro to Reactions",
    "topic_id": 1,
    "topic_name": "Chemical Reactions",
    "course_id": 1,
    "course_name": "Chemistry 3rd Secondary",
    "teacher_name": "Dr Hany",
    "is_submitted": true,
    "submission_id": 5,
    "score": "2.00",
    "status": "graded",
    "submitted_at": "2026-07-18T10:00:00Z"
  }
]

Page layout:

• Page title + subtitle showing total available homeworks
• Filters: Course dropdown, Status dropdown (Not Submitted / Submitted / Graded)
• Card grid � color-coded by status:
  • Not submitted (gray border): "Start Homework" action button
  • Submitted (amber/orange border): "Submitted" badge, "View Submission" action button
  • Graded (green border): Score displayed, "View Results" action button
• Each card shows:
  • Homework title, lecture ? topic ? course breadcrumb
  • Total points
  • Status badge with color
  • Score (if graded)
• Empty state: "No homeworks available. Purchase lectures to access homeworks."

Populates from: homeworks/ endpoint (single call � no merging needed)

Page 14: My Quizzes (Aggregate)

Purpose: View all available quizzes across all purchased lectures. Start, resume, or view quiz results.

APIs to use (from API_STUDENT.md �14):

GET /learning/quizzes/ Response (paginated � use /learning/quizzes/?all=true for non-paginated):

[
  {
    "quiz_id": 1,
    "title": "Quiz 1",
    "description": "Chapter 1 quiz",
    "total_points": "10.00",
    "settings": {
      "timer_minutes": 10,
      "score_visibility": "immediate",
      "answers_visibility": "immediate"
    },
    "lecture_id": 10,
    "lecture_name": "Intro to Reactions",
    "topic_id": 1,
    "topic_name": "Chemical Reactions",
    "course_id": 1,
    "course_name": "Chemistry 3rd Secondary",
    "teacher_name": "Dr Hany",
    "quiz_status": "submitted",
    "submission_id": 15,
    "score": "5.00",
    "score_visible": true,
    "answers_visible": true,
    "started_at": "2026-07-18T10:00:00Z",
    "submitted_at": "2026-07-18T10:30:00Z"
  }
]

Page layout:

• Page title + subtitle showing total available quizzes
• Filters: Course dropdown, Status dropdown (Not Started / In Progress / Submitted)
• Card grid � color-coded by quiz_status:
  • Not started (gray border): "Start Quiz" action button
  • In progress (amber/orange border): Timer indicator, "Resume Quiz" action button
  • Submitted (green or blue border): Score displayed, "View Results" action button
• Each card shows:
  • Quiz title, lecture ? topic ? course breadcrumb
  • Specs: timer, total points
  • Status badge with color and icon
  • Score (if visible)
• Empty state: "No quizzes available. Purchase lectures to access quizzes."

Populates from: quizzes/ endpoint (single call � 3 statuses included, no merging needed)