SuperCards Quiz – Internal Learning & Assessment Platform

Executive Summary

The SuperCards Quiz module is an internal learning and assessment platform embedded inside the broader SuperCards enterprise workspace. Rather than standing up a separate LMS, the module extends the platform’s card-based data model — every quiz is a task card tagged as a Quiz entity, categorized by section, and governed by a Draft → Published → Unpublished lifecycle.

I fully refactored this module from a tangled set of pages into a clean, modular architecture:

• 4 route-level pages orchestrating distinct user journeys
• 11 dedicated components each owning a single UI concern
• 1 Pinia store (quiz-store) with typed API actions
• 1 service layer (quizService.js) against the quizbuilder backend

The refactor preserved deep integration with platform primitives (TaskDetails, PreviewWindow, tag store, media manager) while isolating all quiz-specific logic inside src/modules/quiz/.

Architecture

Module Structure

src/modules/quiz/
├── routes.js                    # 4 authenticated routes under /quiz
├── index.js
├── pages/
│   ├── QuizIndex.vue            # Quick quiz creation entry
│   ├── QuizStudioIndex.vue      # Author workspace (full CRUD)
│   ├── ChallengeYourselfIndex.vue  # Employee discovery & browse
│   └── AttendQuiz.vue           # Timed participation flow
└── components/
    ├── QuizCard.vue             # Dual-mode card (studio / challenge)
    ├── QuizQuestionForm.vue     # Authoring, validation, AI generation
    ├── ExistingQuestionsList.vue # Collapsible edit/delete for saved Qs
    ├── QuizQuestionsDisplay.vue # Live question UI during quiz
    ├── StartQuiz.vue            # Pre-quiz intro screen
    ├── QuizResult.vue           # Score summary & grade badge
    ├── ReviewAnswers.vue        # Post-submission mistake walkthrough
    └── QuizParticipants.vue     # Participant analytics popover

System Topology

flowchart TB
    subgraph Author ["Author Journey"]
        STUDIO["Quiz Studio Page"]
        QFORM["QuizQuestionForm"]
        EXIST["ExistingQuestionsList"]
        TD["TaskDetails (shared)"]
        STUDIO --> QFORM
        STUDIO --> EXIST
        STUDIO --> TD
    end

    subgraph Participant ["Participant Journey"]
        CHALLENGE["Challenge Yourself Page"]
        ATTEND["Attend Quiz Page"]
        START["StartQuiz"]
        DISPLAY["QuizQuestionsDisplay"]
        RESULT["QuizResult"]
        REVIEW["ReviewAnswers"]
        CHALLENGE --> ATTEND
        ATTEND --> START --> DISPLAY --> RESULT --> REVIEW
    end

    subgraph Shared ["Shared Layer"]
        CARD["QuizCard"]
        STORE["quiz-store (Pinia)"]
        API["quizService → quizbuilder API"]
        TAGS["tag-store (status, category)"]
        TASK["task-store (card CRUD, media)"]
        AI["openAIService (GPT-4o-mini)"]
    end

    STUDIO --> CARD
    CHALLENGE --> CARD
    QFORM --> AI
    STORE --> API
    STUDIO --> STORE
    ATTEND --> STORE
    STUDIO --> TAGS
    STUDIO --> TASK
    QFORM --> TASK

Client-to-Cloud Flow

flowchart LR
    UI["Quiz UI Components"] --> STORE["quiz-store"]
    STORE --> SVC["quizService.js"]
    SVC --> API["Laravel quizbuilder API"]
    API --> DB[("PostgreSQL")]

    UI --> TASKSTORE["task-store"]
    TASKSTORE --> CARDS["cards API (create/update/media)"]

    UI --> TAGSTORE["tag-store"]
    TAGSTORE --> TAGSAPI["tags API (Draft/Published/Unpublished)"]

    QFORM["QuizQuestionForm"] --> OPENAI["OpenAI Chat Completions"]

User Journeys

1. Quiz Creation (/quiz/quizzes)

A lightweight entry point where authors create a new quiz card via the platform’s shared creation dialog. On submit, the system tags the card as a Quiz entity type with category and difficulty settings.

2. Challenge Yourself — Assessment Discovery (/quiz/challenge-yourself)

The employee-facing catalog of available assessments. Employees can browse published quizzes by category tabs, search by title, and inspect score distributions.

3. Attend Quiz — Timed Participation (/quiz/attend-quiz/:id)

A structured assessment experience with clear pre-quiz instructions, countdown timers, progress bars, and instant submission.

stateDiagram-v2
    [*] --> Intro: Load questions
    Intro --> Active: Start Quiz (timer begins)
    Active --> Active: Next / Previous question
    Active --> Results: Submit or timeout
    Results --> Review: Review Mistakes
    Review --> Results: Finish Review
    Results --> [*]: Back To Challenges

Timer logic: Countdown from quiz meta time (minutes); auto-submits and advances to results on expiry.

Submission: Normalizes MCQ answers as ID arrays and fill-blank answers as trimmed string arrays before posting to quizbuilder/startQuiz.

6. Quiz Card — Dual-Mode Component (QuizCard)

A single reusable card component serving both author and participant contexts via a mode prop:

Participant popover: Clicking participant count opens QuizParticipants — searchable, sortable list with top score, average, and attempt count per user.

Data Model

Quizzes are not a separate database entity. They are SuperCards task cards enriched with:

Questions live in the quizbuilder service as separate records linked by quiz_card_id.

API Surface (quizService.js)

Refactor Summary — What Changed

Structural

• Extracted 11 components from monolithic page logic
• Introduced dedicated quiz-store with 8 typed actions (create, fetch, update, delete, submit, participants)
• Centralized HTTP in quizService.js with consistent quizbuilder resource naming
• Each page is a thin orchestrator — route params, store calls, event wiring only

UX

• Studio preview panel replaces full-page navigation for editing
• Deep link support (?card_id=) for sharing quiz edit URLs
• Scroll-into-view with highlight when selecting a card
• Collapsible existing questions with search and expand-all
• Four-phase attend flow with timer, progress, and mistake review
• AI question generation with preview-before-apply workflow

Technical

• Validation moved to reactive computed error getters (not inline template checks)
• Question type switching resets form state via watchers (MCQ ↔ fill-blank)
• Answer type switching normalizes correctAnswers (single radio ↔ multi checkbox)
• Submission payload type-normalizes MCQ IDs and fill-blank strings
• ReviewAnswers handles multiple API response shapes via candidate field normalization