Quiz & Assessment Platform

1. Executive Summary

GB5 is building a unified Quiz & Assessment platform so any module — Training (TMS), Work Instructions (WI), Enablement (in-app guidance), and eventually a Learning Management System (LMS) and Interactive Document Management (IDMS) — can attach a scored quiz or a "must-pass" gate to its own content, without every module reinventing question banks, scoring, or gating logic.

The core idea in one sentence: there is now one shared question bank, one quiz-taking/scoring engine (owned by TMS), one shared way to tag content with a Course/Subject/Topic, and one generic "you must pass X before doing Y" gating mechanism — every other module plugs into these instead of building its own.

If you take away one thing: the foundation — taxonomy, quiz engine, gating — is real and working today; the AI/chat/voice/LMS layer is a designed-but-unbuilt roadmap.

2. Concepts & Glossary

Read this before anything else — every later section assumes these terms.

3. What's Built Today ✓ Built & Live

3.1 The Shared Taxonomy — Course / Subject / Topic / Learning Object

Where it lives: GB5Framework (the shared framework layer used by every module) — not inside TMS. Putting it in TMS would have meant every other module had to depend on TMS just to tag its own content. Framework-level masters like Country/City already live here, so this follows the existing convention.

Why two tagging mechanisms? A direct FK column when something has exactly one topic and needs fast filtering (e.g. a quiz question). TTOPICLINK when the relationship is optional or many-to-many (e.g. a Work Instruction touching three topics at once). Both patterns already existed elsewhere in GB5.

Bridging existing TMS data: TMS's question bank already had free-text tag fields before this project. A migration added new Course/Subject/Topic columns, auto-matched existing free-text tags into real Topic rows where possible, and made question-bank searches check both the old tags and the new Topic link during a transition period — nothing broke.

3.2 The Standalone TMS Quiz Engine

Why a new engine, when TMS already had assessments? TMS's existing MSESSIONASSESSMENT only makes sense inside a training programme. There was no way to say "here's a quiz that exists on its own, attached to a Show or WI step, with no training programme involved." That's what MQUIZ adds.

How scoring works

MCQ / True-False / Short Answer are matched exactly (case-insensitive); Multi-Select is compared as a set (order doesn't matter); Matching/Ordering are compared as normalized strings. Anything that can't be auto-graded is left pending for manual review. The final score, pass/fail, and marks are always computed server-side from the actual recorded answers — a client can never submit a score directly.

How question selection works

Instant-mode quizzes pick N random questions from the shared bank, optionally scoped to a Topic. Structured-mode sections each define their own filter and pull that many questions at random (or fixed/weighted) — reusing the same "pull random rows from the shared pool" pattern TMS's assessment-paper system already used.

3.3 Validation Criteria — the Generic "You Must Pass This First" Gate

The problem this solves: before this, any module wanting "you can't do this until you've passed a quiz" would have had to build its own quiz-specific requirement table. Now there's one generic, reusable pair any module can plug into.

• MVALIDATIONCRITERIA — what needs to be true: a type (Skill / Quiz / formal ProgrammeAssessment / Certification), the specific thing, a minimum score/level, and how many days the proof stays valid.
• MVALIDATIONASSIGNMENT — who requires it: which entity (WI, Show, Training Programme, IDMS document…), optionally which step, which criterion, and how strictly (Log = record only, Warn = allow with a warning, Block = hard-stop).
• IValidationCriteriaEvaluator — a shared service answering "what has this person not yet satisfied?" by checking the right underlying proof: a Skill checks the employee's stored level; a Quiz checks for a recent passing attempt; a formal Assessment checks its own attempt table. Nothing new is invented for "where does the proof live."

Illustrative example (not literal seeded data):

Where it's actually wired in: Work Instruction's eligibility check calls this evaluator in two places — a display-only "am I eligible?" check, and the real "start this Work Instruction" action, which refuses to start if a Block-level criterion is unmet (exactly like WI's pre-existing Skill-level block already worked).

Deliberately not touched: WI's own, older Skill/Competency requirement tables were left completely alone — this is an additional layer, not a replacement.

3.4 Enablement Integration

Enablement's "Show" system already had a generic "attach content to this Show" mechanism supporting several content types (CMS article, external URL, file, video, document, Work Instruction, Training Topic). This project adds Quiz as one more attachable type — a Show (or a specific step) can point at a standalone Quiz, with its current title looked up live so a later rename never shows stale text, the same pattern already used for the WI and Training links.

Practical implication: an announcement like "Today's price briefing" could show an Instant-mode, single-question quiz right inside it, without Enablement needing to know anything about how quizzes are scored.

3.5 FLS — What Changed and Why

FLS is a general survey/feedback tool. It always had a "type" field that happened to include "Quiz" and "Test" — but nothing in FLS ever actually scored a quiz; those options were dead ends producing an unscored feedback form.

This is now retired: those two options are archived, and the system actively rejects any new FLS survey built against them, pointing the author at TMS's real Quiz engine instead — avoiding two different, inconsistent places where "a quiz" could mean something different.

4. What's Planned But Not Built ◐ Planned

Nothing in this section exists in the codebase yet. Documented so adjacent work doesn't duplicate this design, and so stakeholders understand where the platform is headed.

4.1 Delivering Quizzes Through Chat & Voice (via EIP)

EIP already has two ways of talking to a user: a one-tap DirectAction (a signed link or WhatsApp-style button — no back-and-forth) planned for simple MCQ/True-False questions, and a full conversational Flow (chat or voice) planned for subjective, adaptive, or spoken questions. Both mechanisms already exist for other purposes — the plan reuses them rather than building new delivery infrastructure.

4.2 EAI — the Planned AI Module

Does not exist yet. Envisioned as a brand-new module whose only job is AI: provider/model choice, versioned prompts, an approval step before AI content goes live, and cost tracking. No vendor has been chosen — every capability is designed to ship first as a clearly labeled "not configured" stub, matching a pattern already used elsewhere in GB5 for an unrelated AI feature.

Who would call it: TMS (question generation, answer evaluation) and EIP (a thin "ask EAI, format for this channel" step). EAI itself would never talk to WhatsApp/Voice directly — that stays EIP's job.

4.3 Dynamic, Data-Driven Quiz Questions

The original motivating idea: a question that pulls a live fact from another module — current price, current stock — so staff are tested on real, current data. A small generic interface would let any data-owning module (Inventory, Finance, HR) expose "facts" for the question-generation capability to use; the live value is frozen onto the question at generation time so grading stays fair even if the real value changes minutes later.

4.4 Voice-Based Q&A

Once chat/voice delivery and AI evaluation exist, voice needs almost no extra work — a call is just another conversation, with an external provider handling speech-to-text and GB5's existing voice-response mechanism handling the reply. The one new planned rule: a scored voice attempt should require an extra identity check (like an OTP), since a phone call can't rely on an existing logged-in session.

4.5 Adaptive Learning Suggestions

After an attempt, planned functionality would look at a learner's history and topic-level gaps and produce a ranked "read this next" list with a short "why" for each item, delivered as a follow-up chat message once chat delivery exists.

4.6 LMS and IDMS

Neither exists yet. Because the taxonomy and gating work were built as shared, framework-level concepts from day one, the plan is that a future LMS "course" becomes a new LMS-owned enrolment table sitting on top of the existing Course/Learning-Object tables — not a new parallel taxonomy. IDMS documents already have a reserved (unused) slot in the tagging system.

5. Known Open Questions

Not yet decided — flagged for whoever picks up the next phase of this roadmap.

• Which AI provider/vendor? Not decided. Everything in Section 4.2 is designed to work with any provider, plugged in later.
• Does the older, separate in-app "Show" quiz-question mechanism get consolidated with the new standalone Quiz, or do both stay? Currently both are allowed to coexist by design, not yet explicitly confirmed as final.
• When EIP and the future EAI module talk to each other, is that in-process or a network call? Depends on how the two modules end up hosted — not yet decided.
• Should WI's older, quiz-unaware Skill-requirement table eventually migrate onto the new generic model? Deliberately deferred to avoid destabilizing a working gate.
• Two-way email as a quiz channel — explicitly out of scope for now.

6. Role-Specific Guides

7. Data Model Quick Reference

8. API Reference ✓ built endpoints only