Exam System — React

1 What you're building

Three screens. Follow the Figma for layout, spacing, and colors.

2 Requirements

Must-have

1. Start an attempt via the API and render the questions from the response (don't hardcode them).
2. One question at a time, with previous / next and an "X من Y" position indicator. Match the option styling from Figma, including the selected state.
3. Track the selected answer per question in state, and autosave each selection to the API.
4. Countdown timer seeded from the API's timeLeft. When it hits zero, auto-submit.
5. Submit → fetch the result → show the Result screen (score %, pass / fail, correct / wrong counts). Don't compute correctness yourself — read it from the result response.
6. Answer Review screen driven by the result data: student's choice, correct choice, explanation.
7. RTL Arabic layout, dark theme, responsive (correct at 375px; usable on desktop).
8. Loading and error states for the async calls (the API adds a small delay so these show).

Stretch — optional, only after the core is solid

• Routing (react-router): /exam/:id → /result → /review, with guards (can't open the result before submitting).
• A question overview / grid to jump around, showing which questions are answered.
• Correct resume: if the app reloads mid-exam, re-hydrate from start (savedAnswer + timeLeft).
• Keyboard accessibility for the options (arrow keys, aria-checked) and focus management.
• Multi-select support (the API exposes maxSelections; our exam is single-select, but designing for it is a plus).

3 Tech constraints

• React + Vite. TypeScript or JavaScript — your choice (TS is a plus).
• State: local state / hooks / Context / Redux — your call; justify it briefly in the README.
• Styling: your choice, but build the components yourself (no pre-made quiz / exam kit).
• Talk to the API with fetch or axios. No XMLHttpRequest.
• Put the API base URL in an env var (e.g. VITE_API_URL).

4 Design tokens

5 API spec

The API is already running — you don't need to start anything. It's seeded with one real exam (اختبار الكهربية — نموذج A, 8 single-choice questions, 30 minutes, pass mark 50%). Every endpoint adds a small artificial delay so your loading states are visible.

Lists available exams.

{
  "exams": [
    {
      "id": 2,
      "name": "اختبار الكهربية — نموذج A",
      "time": 30,
      "totalQuestions": 8,
      "resultsMode": "instant",
      "attemptsUsed": 0,
      "maxAttempts": null,
      "attempt": null
    }
  ]
}

Starts (or resumes) an attempt and returns the questions. Before you submit, calling it again resumes the same attempt (refresh-safe); after you submit, it starts a fresh attempt.

{
  "entryId": 1001,
  "examId": 2,
  "name": "اختبار الكهربية — نموذج A",
  "timeLeft": 1800,
  "endsAt": "2026-07-25T12:00:00.000Z",
  "questions": [
    {
      "id": 7,
      "order": 1,
      "type": "choose",
      "title": "حساب المقاومة R",
      "body": "في الدائرة المقابلة ...",
      "equation": null,
      "isLatin": false,
      "mark": 1,
      "maxSelections": 1,
      "images": [],
      "options": [
        { "index": 1, "text": "8"  },
        { "index": 2, "text": "12" },
        { "index": 3, "text": "16" },
        { "index": 4, "text": "24" }
      ],
      "savedAnswer": []
    }
  ]
}

• timeLeft (seconds) and endsAt are server-authoritative — seed your countdown from them, don't trust the client clock.
• savedAnswer is the previously autosaved answer (array of indexes) — non-empty when resuming.
• images is [] here (real questions have circuit diagrams on a CDN). Render the array if present; otherwise just show the text.

Autosave a single answer as the student picks it. Use the stable option index.

// request body
{ "answer": "2" }          // single, or "1,3" / [1,3] for multi-select

// response
{ "saved": true, "answer": [2] }

Submits the attempt.

{ "status": "submitted", "entryId": 1001, "resultsMode": "instant", "resultsAt": null }

Returns the graded result (this exam releases instantly). Use it for both the Result and Review screens. While the attempt is still running it returns { "status": "running", "timeLeft": … } instead.

{
  "entryId": 1001,
  "examId": 2,
  "status": "marked",
  "released": true,
  "examMark": 6,
  "totalMark": 8,
  "passMark": 50,
  "passed": true,
  "submittedAt": "2026-07-25T12:05:00.000Z",
  "questions": [
    {
      "id": 7,
      "order": 1,
      "title": "حساب المقاومة R",
      "mark": 1,
      "options": [
        { "index": 1, "text": "8",  "isCorrect": false },
        { "index": 2, "text": "12", "isCorrect": true  },
        { "index": 3, "text": "16", "isCorrect": false },
        { "index": 4, "text": "24", "isCorrect": false }
      ],
      "yourAnswer": [2],
      "questionMark": 1,
      "solutionStatus": "correct",
      "explanation": "الحل: بتطبيق قانون أوم ..."
    }
  ]
}

• solutionStatus is correct | incorrect | pending (pending = unanswered).
• Score % = examMark / totalMark × 100. passed is true when that ≥ passMark.

6 What we'll look at

• Correct exam flow and state management (answers, current question, timer, submit → result → review).
• Correct use of the async API — loading / error handling, autosave, reading the score from the server.
• Component structure and readable, modern React (hooks; no dead / commented-out code).
• Design fidelity, including genuine RTL.
• A short README: how to run, what you chose and why, and what you'd do next with more time.