Build a Full-Stack JAMB CBT Practice App in Next.js 15

Learn how to build a responsive, production-ready computer-based testing (CBT) application for JAMB and WAEC exams with timed sessions, real-time navigators, and step-by-step AI explanations.

View Starter Kit on GitHub10 min implementation

4.1.0Architecture Overview

The application utilizes a clean separation of concerns: Next.js App Router handles the UI state and client countdowns, while the official @massteck/aloc-sdk fetches curriculum questions and step-by-step explanations on demand.

[Client Browser] → Next.js App Router (State, Timer, Score)

↓ API Route Handler (/api/assessment)

↓ ALOC Assessment Engine (POST /v1/assessments/generate)

✓ Returns 40-Question Calibrated JAMB Paper + Metadata

4.1.1Step 1: Install @massteck/aloc-sdk

Install the official ALOC TypeScript SDK in your Next.js project:

npm install @massteck/aloc-sdk

4.1.2Step 2: Initialize ALOC Assessment Client

Create a singleton client helper at src/lib/aloc.ts:

import { AssessmentsApi, ExplanationsApi, Configuration } from "@massteck/aloc-sdk";

const config = new Configuration({
  apiKey: process.env.ALOC_API_KEY || "",
  basePath: process.env.ALOC_BASE_URL || "https://dev.aloc.com.ng/api/v1",
});

export const assessmentsClient = new AssessmentsApi(config);
export const explanationsClient = new ExplanationsApi(config);

4.1.3Step 3: Assemble Balanced Examination Paper

Create a route handler at src/app/api/assessment/route.ts to generate calibrated questions with option shuffling:

import { NextResponse } from "next/server";
import { assessmentsClient } from "@/lib/aloc";

export async function POST(req: Request) {
  const { subject, examType = "jamb" } = await req.json();

  const response = await assessmentsClient.generateAssessment({
    generateAssessmentRequest: {
      subject: subject || "mathematics",
      examType: examType,
      preset: "jamb_standard_40",
      shuffleOptions: true,
      seed: `candidate_${Date.now()}`,
    },
  });

  return NextResponse.json(response.data);
}

4.1.4Step 4: Request Step-by-Step AI Explanations

When the student completes the test or requests review on a missed question, query the L3 explanations endpoint:

const explanation = await explanationsClient.explainQuestion({
  id: questionId,
  explainQuestionRequest: { depth: "step_by_step" },
});

// Returns step-by-step derivations & common student mistakes
console.log(explanation.data.explanation);

Ready to try the complete application?

Clone the open-source Next.js starter with full UI, timer, and score cards.

Next Guide: AI Socratic Tutor