Skip to content

Instantly share code, notes, and snippets.

@wahidustoz

wahidustoz/requirements.md

Last active July 5, 2025 03:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save wahidustoz/78b7077d5aa3ea24c5fb144c316828d9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save wahidustoz/78b7077d5aa3ea24c5fb144c316828d9 to your computer and use it in GitHub Desktop.
Download ZIP
Quiz Engine | C# Project
Raw
requirements.md

📚 Quiz engine

Build a two‑mode console app—Teacher and Student—that creates, manages, and runs quizzes, using Spectre.Console for all user interaction.

New in this version

  • Teacher Mode can disable / enable or delete existing quizzes.
  • Optional time‑limited questions feature worth +50 bonus points.

🗂 Table of Contents

  1. Objective
  2. Functional Requirements
  3. Non‑Functional Requirements
  4. Folder Structure
  5. Data Model (Mermaid)
  6. Sample Quiz JSON
  7. Console I/O Samples
  8. Edge Cases
  9. Spectre.Console Usage Requirements
  10. Task Breakdown
  11. Evaluation Rubric
  12. Sequence Diagrams

🎯 1 Objective

Create a console application that lets:

  • Teachers

    1. Build quizzes (MCQ, True/False, Short Answer).
    2. Enable/disable quizzes (disabled quizzes are hidden from students).
    3. Delete quizzes with confirmation.

  • Students

    1. Load an active quiz.
    2. Answer questions via SelectionPrompt / TextPrompt.
    3. Receive an auto‑graded report, with optional half‑score logic for questions answered after their time limit.

✅ 2 Functional Requirements

👩‍🏫 Teacher Mode

Requirement Detail
Main menu SelectionPrompt: Create Quiz, Manage Quizzes, Exit.
Create quiz Enter title & description via TextPrompt.
Add questions MCQ, True/False, Short Answer; repeat until done.
MCQ format Options must be dictionary: "A": "int", etc. Answer stores the key (e.g., "A").
Time‑limited (optional) Teacher may set TimeLimitSeconds (≥ 5 s). Omit for unlimited.
Validation Reject empty prompts, duplicate option keys, invalid time limits.
Summary & save Show a Table; confirm via ConfirmationPrompt before writing JSON.
Manage quizzes List all JSON files via SelectionPrompt. After selection: Enable/Disable, Delete, View Summary.
Delete Requires two confirmations.

👦 Student Mode

Requirement Detail
Quiz list Show only enabled .json files via SelectionPrompt.
Load & header Display in a Panel.
Question flow • MCQ / True‑False: SelectionPrompt (arrow keys + Enter).
• Short Answer: TextPrompt.
Time‑limited logic (bonus) If a question has TimeLimitSeconds, start a countdown.
• Correct within limit → full point.
• Correct after limit → ½ point.
• No answer or wrong answer → 0.
Scoring Auto‑update points (1, 0.5, 0).
Report Table with ✔/✖ and ⏱ icons; overall % and pass/fail (70 % threshold).

🚫 3 Non‑Functional Requirements

  • 100 % Spectre.Console for input/output—no Console.ReadLine/WriteLine.
  • Robust error handling with custom exceptions where appropriate.
  • Disabled quizzes must not appear in Student Mode.

🗂 4 Folder Structure

QuizApp/
│
├── Program.cs
├── Models/
│   ├── Question.cs
│   ├── McqQuestion.cs
│   ├── TrueFalseQuestion.cs
│   ├── ShortAnswerQuestion.cs
│   └── QuizMeta.cs          <-- holds Title, Description, IsActive
│
├── Services/
│   ├── QuizBuilder.cs
│   ├── QuizManager.cs       <-- enable/disable/delete logic
│   ├── QuizRunner.cs
│   └── QuizStorage.cs
│
├── Utilities/
│   └── InputHelper.cs
│
└── Data/
    └── quizzes/

🏗 5 Data Model

classDiagram
    direction TB
    class QuizMeta {
        +string Title
        +string Description
        +bool IsActive
        +List~Question~ Questions
    }

    class Question {
        +string Prompt
        +int? TimeLimitSeconds
        +abstract double CheckAnswer(string answer, double elapsedSec)
    }

    class McqQuestion {
        +Dictionary~string,string~ Options
        +string AnswerKey
    }

    class TrueFalseQuestion {
        +bool CorrectAnswer
    }

    class ShortAnswerQuestion {
        +string CorrectAnswer
    }

    QuizMeta *-- Question
    Question <|-- McqQuestion
    Question <|-- TrueFalseQuestion
    Question <|-- ShortAnswerQuestion
Loading

📑 6 Sample Quiz JSON (time‑limit demo)

{
  "Title": "C# Basics",
  "Description": "Covers primitive types and control flow.",
  "IsActive": true,
  "Questions": [
    {
      "Type": "MCQ",
      "Prompt": "Which is a value type in C#?",
      "Options": {
        "A": "string",
        "B": "int",
        "C": "object",
        "D": "dynamic"
      },
      "Answer": "B",
      "TimeLimitSeconds": 20   // answer in 20 s for full credit
    },
    {
      "Type": "TrueFalse",
      "Prompt": "The 'var' keyword implies dynamic typing.",
      "CorrectAnswer": false
    },
    {
      "Type": "ShortAnswer",
      "Prompt": "What keyword defines a constant?",
      "CorrectAnswer": "const",
      "TimeLimitSeconds": 15
    }
  ]
}

💻 7 Console I/O Samples

Teacher Mode – Manage Quizzes

[ Manage Existing Quizzes ]
❯ C# Basics   (active)
  OOP Review   (disabled)

Actions for **C# Basics**
❯ Disable Quiz
  Delete Quiz
  View Summary
  Back

Student Mode – Time‑Limited Question

[ Question 1 of 3 ]  ⏱ 20s
Which is a value type in C#?

❯ A: string
  B: int
  C: object
  D: dynamic

(timer counts down; answer after 22 s but correct)
⚠ Time exceeded. Half credit awarded.

⚠ 8 Edge Cases

  • Attempting to start Student Mode when no active quizzes exist.
  • Deleting a quiz that is currently disabled.
  • Teacher disabling an already disabled quiz.
  • Time limit ≤ 0 or < 5 seconds (reject).
  • Student presses Esc or closes prompt before answering (treat as wrong).
  • Half‑credit rounding (0.5 increments).

🖼 9 Spectre.Console Usage Requirements

Purpose API
Main & sub‑menus SelectionPrompt<string>()
Confirmations ConfirmationPrompt()
Text input TextPrompt<string>()
Timer display LiveDisplay, Status(), or custom markup refresh
Tables Table()
Panels / headings Panel(), Rule()
Color feedback Markup()

⏱ 10 Task Breakdown (≈ 16 hrs core + 2‑3 hrs bonus)

Task Hours
Design models & interfaces 2
Implement Teacher Mode (create) 3
Implement Teacher Mode (manage) 1
Implement Student Mode 4
JSON save/load layer 2
Spectre polishing 2
Edge case handling & tests 2
Bonus: time‑limit engine +2–3

🧾 11 Evaluation Rubric /150

Area Points
OOP design & readability 15
Teacher Mode – create 15
Teacher Mode – manage 10
Student Mode 15
JSON persistence reliability 15
Full Spectre.Console usage 15
Error/edge handling 15
All mandatory edge cases met 15
Bonus: time‑limit questions +50

(Max = 150; graders scale to 100 % for final grade.)

🔄 12 Sequence Diagrams

12.1 Teacher Mode (Create / Manage)

sequenceDiagram
    participant T as Teacher
    participant App as ConsoleApp
    participant FS as FileSystem

    T->>App: Launch Teacher Mode
    App-->>T: Main menu (Create / Manage)
    alt Create Quiz
        App-->>T: Prompt meta
        loop Add Qs
            App-->>T: Select q‑type
            T-->>App: Provide details
        end
        App-->>T: Show summary -> confirm save
        T-->>App: Confirm
        App->>FS: Write JSON
        FS-->>App: OK
    else Manage Quiz
        App->>FS: List quizzes
        FS-->>App: File list
        App-->>T: Select quiz
        T-->>App: Choose Disable/Delete/View
        alt Disable
            App->>FS: Toggle IsActive
        else Delete
            App-->>T: Confirm x2
            T-->>App: Confirm
            App->>FS: Delete file
        end
    end
    App-->>T: Result message
Loading

12.2 Student Mode (with Time Limit)

sequenceDiagram
    participant S as Student
    participant App as ConsoleApp
    participant FS as FileSystem
    S->>App: Launch Student Mode
    App->>FS: List active quizzes
    FS-->>App: Quiz list
    App-->>S: Select quiz
    S-->>App: Choose
    App->>FS: Read JSON
    FS-->>App: Quiz data
    loop Each question
        App-->>S: Show prompt (+timer if set)
        App-->>S: SelectionPrompt/TextPrompt
        S-->>App: Answer (and elapsed time)
        App-->>S: Evaluate ✔ / ✖ / ⏱½
    end
    App-->>S: Display final report
Loading

13  End‑to‑End I/O Examples

The following transcripts demonstrate every realistic branch the user can take in Teacher and Student modes, including success paths, validation errors, confirmation prompts, disabled quizzes, time‑limited questions, half credit, and “no active quiz” handling.
All prompts are powered by Spectre.Console components (shown in bold).

13.1 Teacher Mode – Full Cycle

A. Create a New Quiz (happy path) 
──────────────  TEACHER MODE  ──────────────
❯ Create Quiz
  Manage Quizzes
  Exit
─────────────────────────────────────────────

[ Title of new quiz ]           (TextPrompt)
> C# Basics

[ Short description ]           (TextPrompt)
> Covers primitive types and control flow.

─────────────────────────────────────────────
Add questions to “C# Basics”
❯ Add MCQ
  Add True/False
  Add Short Answer
  Finish Quiz
─────────────────────────────────────────────

(After choosing Add MCQ)

[ Question prompt ]             (TextPrompt)
> Which is a value type in C#?

[ Option A ]                    (TextPrompt)
> string
[ Option B ]
> int
[ Option C ]
> object
[ Option D ]
> dynamic

[ Correct option key ]          (SelectionPrompt) 
❯ A
  B
  C
  D
(Teacher moves to B)  Enter

[ Time limit in seconds (ENTER for none) ]   (TextPrompt)
> 20

✔ MCQ added.

(Add True/False, Add Short Answer …)

─────────────────────────────────────────────
All questions entered.  Summary:
┌─────┬────────────────────────────────────────────┬─────────┐
│ #   │ Type            │ Prompt                               │
├─────┼─────────────────┼───────────────────────────────────────┤
│ 1   │ MCQ (20 s)      │ Which is a value type in C#?          │
│ 2   │ True/False      │ 'var' implies dynamic typing.         │
│ 3   │ Short Answer    │ Keyword that defines a constant?      │
└─────┴─────────────────┴───────────────────────────────────────┘
Save quiz?                     (ConfirmationPrompt)  [y/N]
> y

🗂 Writing file “C# Basics.json” … done.
[green]Quiz created successfully![/]
B. Validation Error — Duplicate MCQ Option Key 
Add MCQ
[ Option A ]
> int
[ Option A ]  (again by mistake)
> integer
[red]Duplicate option key “A”. Option keys must be unique (A‑Z).[/]
C. Overwrite Existing Quiz — Decline 
Quiz titled “C# Basics” already exists.
Overwrite?  (ConfirmationPrompt) [y/N]
> n
[grey]File not overwritten. Returning to main menu…[/]
D. Manage Quizzes — Disable, Enable, Delete 
──────────  MANAGE QUIZZES  ──────────
❯ C# Basics         (active)
  OOP Review        (disabled)
  Back
───────────────────────────────────────

(Select “C# Basics”)

Actions:                      (SelectionPrompt)
❯ Disable Quiz
  Delete Quiz
  View Summary
  Back

> Disable Quiz
Confirm disable “C# Basics”?  (ConfirmationPrompt) [y/N]
> y
[green]Quiz disabled.[/]

──────────  MANAGE QUIZZES  ──────────
  C# Basics         (disabled)
❯ OOP Review        (disabled)
  Back

(Select “OOP Review”)

Actions:
❯ Enable Quiz
  Delete Quiz
  View Summary
  Back

> Enable Quiz
[green]Quiz enabled.[/]

(Delete flow)

Actions:
  Enable/Disable
❯ Delete Quiz

Danger! This will permanently delete “C# Basics”.
Type DELETE to confirm →  
> del
[red]Incorrect confirmation string. Delete aborted.[/]

Type DELETE to confirm →  
> DELETE
Are you absolutely sure?  (ConfirmationPrompt) [y/N]
> y
File removed.

13.2 Student Mode – Full Cycle

E. No Active Quizzes 
──────────────  STUDENT MODE  ──────────────
(no active quizzes found)
Ask your teacher to enable at least one quiz.
─────────────────────────────────────────────
F. Take Quiz – Mixed Results + Time Limit Scenarios 
──────────────  STUDENT MODE  ──────────────
Select a quiz:                (SelectionPrompt)
❯ C# Basics
  OOP Review
─────────────────────────────────────────────

╭────────────────────────────────────────────╮
│  C# Basics                                │
│  Covers primitive types and control flow. │
╰────────────────────────────────────────────╯
Press ENTER to begin…

[ Question 1 / 3 | ⏱ 20 s ]
Which is a value type in C#?
❯ A: string
  B: int
  C: object
  D: dynamic
(Answer chosen within 12 s → B)  
[green]✔ Correct![/]

[ Question 2 / 3 ]
'var' implies dynamic typing.
❯ True
  False
(Selected “True”)  
[red]✖ Incorrect.[/]

[ Question 3 / 3 | ⏱ 15 s ]
Keyword that defines a constant?
(15‑second countdown shown with Status spinner)
> const
(Time taken: 19 s)  
[yellow]⚠ Time exceeded. Half credit awarded.[/]

─────────────────  RESULTS  ─────────────────
┌─────┬──────────────────────────────────┬─────────┐
│ #   │ Question                         │ Score   │
├─────┼──────────────────────────────────┼─────────┤
│ 1   │ value type in C#?                │ [green]1.0[/] │
│ 2   │ 'var' implies dynamic typing.    │ [red]0.0[/]  │
│ 3   │ keyword for constant             │ [yellow]0.5[/]│
└─────┴──────────────────────────────────┴─────────┘
Total: 1.5 / 3  (50 %) → [red]Fail[/]
G. Invalid Selection Key (Prevented by UI)

Because MCQ and True/False use SelectionPrompt, the user cannot enter an invalid key—arrow keys restrict the choice set.
If they press Esc or CTRL‑C, you should catch the OperationCanceledException and treat the answer as wrong (0 pts).

[ Question 1 / 3 ]
Which is a value type in C#?
(ESC pressed)
[grey]No answer selected. Marked as incorrect.[/]

These exhaustive transcripts cover all paths that must be handled in code.
Good luck, and happy coding! 🚀

@wahidustoz
Copy link
Author

wahidustoz commented Jul 5, 2025 •
edited
Loading

👩‍🏫 Teacher Mode — How QuizBuilder and QuizManager Work

🚪 Entry Point

When the user selects "Teacher Mode" from the main menu:

new QuizBuilder().Run();

🧩 Role of QuizBuilder

QuizBuilder acts as the controller for Teacher Mode.
It routes the teacher to either creating or managing quizzes.

🧭 Main Menu Prompt

public void Run()
{
    while (true)
    {
        var choice = InputHelper.AskSelection("Teacher Menu", new[]
        {
            "➕ Create New Quiz",
            "🛠 Manage Existing Quizzes",
            "🔙 Back to Main Menu"
        });

        switch (choice)
        {
            case "➕ Create New Quiz":
                CreateQuiz(); // Handles new quiz creation
                break;

            case "🛠 Manage Existing Quizzes":
                new QuizManager().Run(); // Delegates to QuizManager
                break;

            case "🔙 Back to Main Menu":
                return;
        }
    }
}

🏗️ What CreateQuiz() Does

Inside QuizBuilder, the CreateQuiz() method:

  • Prompts for:
    • ✅ Quiz Title (TextPrompt)
    • ✅ Description (TextPrompt)
  • Creates an empty QuizMeta object
  • Starts a loop to add questions:
    • MCQ
    • True/False
    • Short Answer
  • Validates all entries
  • Offers optional time limits
  • Renders a Table summary
  • Confirms saving via ConfirmationPrompt
  • Calls QuizStorage.Save() to write JSON

🔧 What QuizManager.Run() Does

Once the teacher selects "Manage Existing Quizzes",
control is passed to QuizManager:

Responsibilities:

  • List all quizzes from Data/quizzes/
  • Let the user:
    • ✅ Enable/Disable selected quiz
    • ❌ Delete a quiz (with 2 confirmations)
    • 📄 View Summary in a table
  • Update the quiz metadata (IsActive flag)
  • Remove file if deleted

🔁 Diagram — Teacher Mode Lifecycle

flowchart TD
    A[Start: Teacher Mode Selected]
    B[QuizBuilder.Run]
    C[Main Menu: SelectionPrompt]
    D[CreateQuiz]
    E[QuizManager.Run]
    F[Return to Main Menu]

    A --> B --> C
    C --> D
    C --> E
    C --> F

    D --> D1[Prompt for title + description]
    D1 --> D2[Loop: Add Questions]
    D2 --> D3[Show summary table]
    D3 --> D4[Confirm and Save as JSON]

    E --> E1[List all quizzes]
    E1 --> E2[Select quiz to manage]
    E2 --> E3[Action: Enable/Disable/Delete/View]
    E3 --> E4[Perform selected action]
    E3 --> F
Loading

🎯 Why Split the Logic?

Class Responsibility
QuizBuilder Create new quizzes from scratch
QuizManager Manage existing quizzes

✅ Benefits:

  • Clear separation of concerns (SRP)
  • Better readability and maintenance
  • Easier to test independently

Let me know if you'd like this shown as a Mermaid diagram too!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment