The Exam Engine

Source: Dev.to

Chapter 5: The Exam Engine

This chapter is the most crucial core of the entire LMS system. At this stage, Academic Suite no longer just manages static data, but begins to handle time, status, and user behavior in real‑time.

The exam engine is responsible for ensuring that:

• Exams can only be accessed at the specified time
• Every student receives a fair time allocation
• Exam status remains consistent even in the event of a refresh, reconnect, or network disruption

Small errors in this part can result in grading unfairness or even exam system leaks.

5.1 Design Philosophy: Quiz vs ExamBatch

A common mistake in online exam systems is mixing question content and exam schedules into a single entity. Academic Suite explicitly separates the two:

Quiz

A collection of questions and answer options. It is static and reusable.

ExamBatch

A representation of an exam administration for a specific context (class, time, token). It is dynamic.

Benefits of This Separation

With this separation, a single quiz can be used multiple times without data duplication:

• Quiz “Basic Math” → Class A Batch (Monday 08:00)
• Same Quiz → Class B Batch (Tuesday 10:00)

This approach makes the system:

• More flexible
• Easier to scale
• Safer against schedule changes

5.2 Exam State Machine

An exam is a time‑based process, so its status must change automatically:

• scheduled
• active
• finished

Instead of using a cron job to periodically update batch status, Academic Suite uses a Lazy State Update approach.

Lazy State Update

Exam status is evaluated every time there is a request, based on the current server time. The implementation is found in handlers/batch.go:

func GetBatches(c *fiber.Ctx) {
    now := time.Now()

    if now.After(batch.StartTime) && now.Before(batch.EndTime) {
        batch.Status = "active"
    } else if now.After(batch.EndTime) {
        batch.Status = "finished"
    }
}

Benefits of This Approach

• Does not require a background worker
• No risk of out‑of‑sync status
• Logic is simple and easy to test

The exam status is always consistent with the actual server time.

5.3 Secure Timer: Server‑Side Time Authority

One fatal mistake in online exam systems is trusting the time on the client side. The clock on a student’s browser or operating system can be manipulated, so a JavaScript‑based timer cannot be used as a source of truth.

Solution: Server‑Side Time Authority

Academic Suite makes the server the sole source of truth for time. The frontend periodically calls the endpoint:

GET /api/attempts/:id/time

The backend then calculates the remaining time based on:

• Exam start time
• Total pause time
• Batch duration

elapsed := time.Now().Sub(attempt.StartedAt)
effectiveElapsed := elapsed - attempt.TotalPausedTime
remaining := batch.Duration - effectiveElapsed

If remaining <= 0, the backend decisively:

• Rejects new answers
• Automatically ends the attempt

With this approach, time manipulation on the client side becomes irrelevant.

5.4 Exam Pause & Resume Features

In real‑world conditions, exams can be interrupted by external factors such as power outages, network disruptions, or emergencies. Academic Suite provides a Freeze / Resume Batch feature.

Pause Mechanism

When a batch is paused, the backend records PausedAt. While the pause status is active, student time does not decrease.

Resume Mechanism

When the batch is resumed, the time difference between PausedAt and the current time is calculated and added to TotalPausedTime. This ensures:

• All students receive fair time treatment
• No attempts are disadvantaged due to conditions outside the system’s control

5.5 Exam Token

As an additional security layer, each ExamBatch can be protected with an exam token. Even if the student is logged in and the exam time is active, they cannot start an attempt without entering a valid token.

Benefits of Exam Tokens

• Prevents students from entering early
• Reduces the risk of exams being accessed by unauthorized parties
• Gives full control to exam proctors

These tokens are optional but highly recommended for formal exams.

Chapter Summary

In this chapter, we built the exam engine, the heart of Academic Suite. We covered:

• Separation of exam content and context
• Time‑based state machine with lazy updates
• Secure server‑side timer
• Pause and resume mechanisms
• Additional security via exam tokens

The exam system, however, is not fully secure without protecting data integrity and participant behavior. In Chapter 6, we will discuss Data Integrity & Anti‑Cheating strategies, including handling reconnects, multi‑tabs, and other cheating attempts.