Developer & QA Documentation

Teacher & Student Testing Flow

Complete walkthrough for testing teacher test authoring, the proctor waiting room gate, instant database demo payments (no Paystack required), and the admin platform revenue ledger.

Teacher Dashboard → Create Paid Test Django Admin

1 System Architecture & Lifecycle

Phase 1

Teacher Setup

Teacher creates a paid test, sets price (min ₦200), selects topics, and checks "Require Teacher Approval to Start".

Phase 2

Demo Checkout

Student visits the public share link. Clicks "⚡ Instant Demo Payment". Verified directly in the DB; 10-character PIN issued instantly.

Phase 3

Waiting Lobby Gate

Student enters PIN and is held in the waiting lobby. HTMX polls every 3s. Student cannot view questions until teacher starts exam.

Phase 4

Proctor Unlock & Exam

Teacher clicks "Unlock & Start Exam". Student auto-redirects into CBT test. 20% platform cut & 80% teacher wallet update in real time.

Step-by-Step QA Verification

1

Teacher Publishes Test with Waiting Room Active

1. Navigate to Create Paid Test.

2. Enter a test title, description, and price (e.g., ₦500.00).

3. Select one or more topics with available questions.

4. Check the box labeled "Require Teacher Approval to Start" (this activates the waiting room gate).

5. Click Publish Test. You will be redirected to the Teacher Dashboard where you can see the test with a status badge Locked (Waiting Room).

6. Click Copy Link next to your newly created test.

2

Student Registration via Demo Payment (Zero Paystack Required)

1. Open a new Incognito or Private Browsing window (or a different browser) so you test as an unauthenticated or student user.

2. Paste the copied test link (e.g., http://localhost:8000/monetization/tests/<share_code>/).

3. Fill in the student checkout form:

  • Full Name: e.g. "Ada Lovelace"
  • Email: e.g. "ada@example.com"
  • Phone Number: e.g. "08012345678"

4. Click the green button: "⚡ Instant Demo Payment (Database Only — Zero Setup)".

5. Payment is recorded and verified cleanly in the database without hitting external Paystack servers. The student is immediately presented with their Purchase Receipt and their secret 10-character Test PIN.

3

Student Waiting Lobby Gate

1. From the receipt page, the student clicks "Start Test Now", or navigates to /enter/ and inputs their PIN.

2. Because the teacher has not yet unlocked the exam, the student is redirected to the Waiting Room (/waiting/).

3. In the waiting room, students see:

  • A pulsing radar indicator: "Waiting for teacher to start the exam..."
  • Their saved Access PIN in bold mono font so they don't lose it.
  • Real-time HTMX polling checking every 3 seconds for the teacher's start trigger.
Security note: Direct attempts to bypass the waiting room or call the practice session URL before approval are rejected with a redirect back to the waiting room.
4

Teacher Unlocks Exam (Proctor Control)

1. Switch back to your teacher browser window.

2. On the Teacher Dashboard, click "View students & scores" on the test.

3. Notice the banner: Exam is LOCKED (Waiting Room Active).

4. Click "Unlock & Start Exam for Students".

5. Switch to the student's browser window. Within 3 seconds, without refreshing, the student's waiting room automatically launches them into the active CBT test session!

5

Admin Platform Earnings & Operations

1. As a staff member, visit Admin Platform Earnings.

2. Review the financial metrics:

  • Gross Sales Volume: Total ₦ generated from all purchases.
  • Platform Cut (20%): Automatic revenue retention for KalmiPrep.
  • Teacher Share (80%): Credited directly into teacher wallets.
  • Pending Applications: Approve or reject tutor and lecture house applications with one click.
  • Recent Purchases: Real-time audit log of student email, amount, and reference.

Endpoint & URL Reference

Route Role Description
/monetization/ Teacher Teacher dashboard, wallet balance, published tests, copy links
/monetization/tests/new/ Teacher Create new paid test with optional approval gate
/monetization/tests/<uuid>/ Student Public checkout page with Demo DB payment & Paystack options
/monetization/tests/<uuid>/waiting/ Student Waiting room polling lobby while teacher has not yet unlocked test
/monetization/tests/<uuid>/results/ Teacher Leaderboard & Proctor Controls (Unlock & Start Exam / Lock Gate)
/monetization/staff/earnings/ Admin/Staff Platform 20% cut ledger, gross volume, teacher application reviews
/docs/ All This interactive testing & architecture documentation page